ticket-to-pr 1.0.0 → 1.2.0

package/README.md

@@ -2,6 +2,8 @@
 
 # TicketToPR
 
+[![npm version](https://img.shields.io/npm/v/ticket-to-pr.svg)](https://www.npmjs.com/package/ticket-to-pr)
+
 ### Drag a Notion ticket. Get a pull request.
 
 AI-powered development automation that turns your Notion backlog into shipped code.
@@ -32,6 +34,7 @@ TicketToPR clears that pile. Toss tickets on your Notion board, drag to Review,
 - **AI scores before AI codes** — every ticket gets an ease/confidence rating and implementation spec before a single line is written. You always decide go/no-go.
 - **Your codebase, your rules** — Claude reads your project's `CLAUDE.md` and follows your conventions, patterns, and constraints.
 - **Build validation** — code must pass your build command before anything pushes. No broken PRs.
+- **Blocked file guardrails** — configure glob patterns for files the agent must never touch (e.g. migrations, DB schemas). Enforced via prompt injection into both review and execute agents + hard post-diff validation.
 - **Full audit trail** — cost, duration, scores, branch name, PR link, and agent comments posted directly on the Notion ticket.
 - **Cost transparency** — every ticket shows exactly what it cost. Simple tasks run $0.35-0.55.
 - **Human-in-the-loop** — nothing merges without a developer reviewing the PR.
@@ -102,24 +105,22 @@ The rhythm is **you, AI, you, AI, AI, you** — three human touchpoints, three A
 ## Quick Start
 
 ```bash
-git clone https://github.com/JohnRiceML/ticket-to-pr.git
-cd ticket-to-pr
-npm install
+npm install -g ticket-to-pr
 
 # Guided setup — configures Notion, projects, and .env.local
-npx tsx index.ts init
+ticket-to-pr init
 
 # Verify everything is working
-npx tsx index.ts doctor
+ticket-to-pr doctor
 
 # Test connection
-npx tsx index.ts --dry-run --once
+ticket-to-pr --dry-run --once
 
 # Run once (process all pending tickets)
-npx tsx index.ts --once
+ticket-to-pr --once
 
 # Run continuously (polls every 30s)
-npx tsx index.ts
+ticket-to-pr
 ```
 
 ## Prerequisites
@@ -186,7 +187,7 @@ https://www.notion.so/yourteam/abc123def456789...?v=...
 The guided setup configures everything interactively — Notion credentials, tools, models, and projects:
 
 ```bash
-npx tsx index.ts init
+ticket-to-pr init
 ```
 
 Init validates as you go: invalid Notion tokens and database IDs are rejected immediately (you'll be re-prompted), and it warns about missing tools. If you re-run `init` later, it detects existing config and asks whether to update or start fresh.
@@ -194,10 +195,10 @@ Init validates as you go: invalid Notion tokens and database IDs are rejected im
 ### 4. Verify
 
 ```bash
-npx tsx index.ts doctor
+ticket-to-pr doctor
 # Should show all checks passing, including database schema validation
 
-npx tsx index.ts --dry-run --once
+ticket-to-pr --dry-run --once
 # Should connect to Notion and report "No tickets to process"
 ```
 
@@ -209,7 +210,7 @@ npx tsx index.ts --dry-run --once
 
 | Command / Flag | Behavior |
 |----------------|----------|
-| `init` | Guided setup — validates Notion credentials live, configures projects, writes `.env.local` and `projects.json`. Detects existing config on re-run. |
+| `init` | Guided setup — validates Notion credentials live, auto-detects build commands, generates starter `CLAUDE.md`, configures projects, writes `.env.local` and `projects.json`. Detects existing config on re-run. |
 | `doctor` | Diagnostic check — verifies environment, Notion connectivity, database schema, tools, and projects |
 | *(none)* | Continuous polling every 30s |
 | `--once` | Poll once, wait for agents to finish, exit |
@@ -218,7 +219,7 @@ npx tsx index.ts --dry-run --once
 
 ### `init` — Guided Setup
 
-Run `npx tsx index.ts init` to configure TicketToPR interactively:
+Run `ticket-to-pr init` to configure TicketToPR interactively:
 
 ```
 TicketToPR Setup
@@ -246,7 +247,15 @@ Step 4: Projects
   Project name: MyApp
   Directory: /Users/you/Projects/MyApp
   ✓ Git repo  git@github.com:you/MyApp.git
-  Build command (optional): npm run build
+  Build command (npm run build):                    ← auto-detected from package.json
+  Base branch (main):
+  Glob patterns the agent must never touch (e.g. **/migrations/**, prisma/schema.prisma, **/*.sql)
+  Blocked file patterns (optional, comma-separated):
+  Skip automatic PR creation? (N):
+  Detected: TypeScript, Next.js, Tailwind CSS       ← auto-detected from project files
+  Generate starter CLAUDE.md? (Y):
+  ✓ Generated CLAUDE.md  /Users/you/Projects/MyApp/CLAUDE.md
+  Edit it to add project-specific rules and conventions.
 
   Add another project? (N):
 
@@ -255,18 +264,20 @@ Step 5: Save
   ✓ Updated projects.json
 
 Ready!
-  Test:  npx tsx index.ts doctor
+  Test:  ticket-to-pr doctor
   Docs:  https://www.tickettopr.com
 ```
 
 - **Blocks on bad config** — invalid Notion tokens and database IDs are rejected and re-prompted (won't save broken credentials)
+- **Auto-detects build command** — reads `package.json`, `Cargo.toml`, `go.mod`, `pyproject.toml`, or `Makefile` and pre-fills the build command. Press Enter to accept or override.
+- **Generates starter CLAUDE.md** — detects your project stack (language, framework, test runner, CSS, ORM) and offers to generate a `CLAUDE.md` with build commands, code style, and file structure. Both agents read this file for context.
 - **Re-run safe** — detects existing `.env.local` and `projects.json`, asks "update" or "start fresh"
 - **Free tier guard** — warns if you configure multiple projects without a Pro license
 - Masks existing secrets when showing defaults
 
 ### `doctor` — Diagnostic Check
 
-Run `npx tsx index.ts doctor` to verify your setup. It checks everything non-interactively:
+Run `ticket-to-pr doctor` to verify your setup. It checks everything non-interactively:
 
 ```
 TicketToPR Doctor
@@ -296,8 +307,10 @@ Tools:
 
 Projects:
   ✓ MyApp                     /Users/you/Projects/MyApp
+  ○   Base branch             main (auto-detected)
+  ○   Blocked files           none configured
 
-Summary: 14 passed, 1 warnings, 0 failed
+Summary: 14 passed, 3 warnings, 0 failed
 Docs: https://www.tickettopr.com
 ```
 
@@ -314,9 +327,9 @@ Docs: https://www.tickettopr.com
 3. **Project**: Your project name from `projects.json`
 4. **Description**: `Create a simple GET endpoint at /api/test/hello that returns { message: "hello world" }`
 5. Drag to **Review** column
-6. Run `npx tsx index.ts --once` and watch it score the ticket
+6. Run `ticket-to-pr --once` and watch it score the ticket
 7. Check Notion — ticket should be in **Scored** with Ease, Confidence, Spec, Impact filled in
-8. Drag to **Execute**, run `npx tsx index.ts --once` again
+8. Drag to **Execute**, run `ticket-to-pr --once` again
 9. Check Notion — ticket should be in **PR Ready** with Branch, Cost, and PR link
 
 Typical cost for this test: **~$0.49** ($0.22 review + $0.27 execute).
@@ -335,12 +348,10 @@ cat > ~/Library/LaunchAgents/com.ticket-to-pr.plist << 'EOF'
     <string>com.ticket-to-pr</string>
     <key>ProgramArguments</key>
     <array>
-        <string>npx</string>
-        <string>tsx</string>
-        <string>index.ts</string>
+        <string>ticket-to-pr</string>
     </array>
     <key>WorkingDirectory</key>
-    <string>/Users/YOUR_USERNAME/Projects/ticket-to-pr</string>
+    <string>/Users/YOUR_USERNAME</string>
     <key>RunAtLoad</key>
     <true/>
     <key>KeepAlive</key>
@@ -381,7 +392,7 @@ tail -f ~/Projects/ticket-to-pr/bridge.log
 The review agent explores your codebase without modifying anything:
 
 - **Tools**: Read, Glob, Grep, Task
-- **Context**: Reads your project's `CLAUDE.md` for architecture rules
+- **Context**: Reads your project's `CLAUDE.md` for architecture rules. If `blockedFiles` are configured, the review agent factors those constraints into scoring.
 - **Output**: Ease score, confidence score, implementation spec, impact report, affected files, risks
 - **Budget**: $2.00 max, 25 turns max
 - **Typical cost**: $0.15 - $0.50
@@ -414,14 +425,16 @@ The execute agent implements the code based on the spec:
 
 ### Git Workflow
 
-1. TicketToPR creates branch `notion/{8-char-id}/{ticket-slug}` from the default branch (auto-detected — `main`, `master`, etc.)
-2. Claude implements changes and makes atomic commits
-3. TicketToPR runs your build command (if configured)
-4. Build passes: pushes branch to origin
-5. Creates a GitHub PR via `gh pr create` targeting the default branch (includes spec, impact, Notion link, cost)
-6. PR URL written back to the Notion ticket
-7. Ticket moves to **PR Ready**
-8. Build fails: branch kept locally, ticket moves to **Failed**
+1. TicketToPR **fetches the latest** from `origin/<baseBranch>` (configurable per project, auto-detected by default)
+2. Creates branch `notion/{8-char-id}/{ticket-slug}` based on the fresh remote state
+3. Claude implements changes and makes atomic commits
+4. TicketToPR runs your build command (if configured)
+5. If `blockedFiles` patterns are configured, validates no off-limits files were touched
+6. Build passes + no blocked file violations: pushes branch to origin
+7. Creates a GitHub PR via `gh pr create` targeting the base branch (unless `skipPR` is enabled)
+8. PR URL written back to the Notion ticket
+9. Ticket moves to **PR Ready**
+10. Build fails or blocked file violation: no code is pushed, ticket moves to **Failed**
 
 ## Costs
 
@@ -480,6 +493,9 @@ Project configuration in `projects.json`:
 |-------|---------|
 | `projects.<name>.directory` | Absolute path to the project's local git repo |
 | `projects.<name>.buildCommand` | Optional build validation command (e.g. `npm run build`) |
+| `projects.<name>.baseBranch` | Optional base branch (e.g. `develop`). Falls back to auto-detected default (`main`/`master`). |
+| `projects.<name>.blockedFiles` | Optional array of glob patterns the agent must never touch (e.g. `["**/migrations/**", "**/*.sql"]`) |
+| `projects.<name>.skipPR` | Optional boolean. Set `true` to push the branch but skip automatic PR creation. |
 
 ## Project Structure
 
@@ -505,24 +521,30 @@ ticket-to-pr/
 
 ## Adding a New Project
 
-Add to `projects.json` (or re-run `npx tsx index.ts init`):
+Add to `projects.json` (or re-run `ticket-to-pr init`):
 
 ```json
 {
   "projects": {
     "MyProject": {
       "directory": "/absolute/path/to/project",
-      "buildCommand": "npm run build"
+      "buildCommand": "npm run build",
+      "baseBranch": "develop",
+      "blockedFiles": ["**/migrations/**", "prisma/schema.prisma", "**/*.sql"],
+      "skipPR": false
     }
   }
 }
 ```
 
-1. `buildCommand` is optional — omit it if you don't need build validation
-2. The directory must be a git repo with an `origin` remote
-3. If the project has a `CLAUDE.md`, both agents will read it for context
-4. Create Notion tickets with `Project` set to the exact key name (case-sensitive)
-5. Run `npx tsx index.ts doctor` to verify — it will check the schema and project match
+1. All fields except `directory` are optional — omit any you don't need
+2. `baseBranch` — which branch to base feature branches on. Auto-detected (`main`/`master`) if omitted.
+3. `blockedFiles` — glob patterns the agent must never touch. Enforced via prompt injection into both review and execute agents, plus a hard post-diff validation before push.
+4. `skipPR` — set `true` to push branches without creating a PR (useful for repos that use a different PR workflow)
+5. The directory must be a git repo with an `origin` remote
+6. If the project has a `CLAUDE.md`, both agents will read it for context
+7. Create Notion tickets with `Project` set to the exact key name (case-sensitive)
+8. Run `ticket-to-pr doctor` to verify — it shows base branch, blocked files, and skip PR status per project
 
 ## Error Handling
 
@@ -533,6 +555,7 @@ Add to `projects.json` (or re-run `npx tsx index.ts init`):
 | Review agent fails | Ticket -> Failed, error written to Impact field with actionable detail |
 | Execute agent fails | Worktree cleaned up, ticket -> Failed |
 | Build validation fails | Ticket -> Failed with command, directory, and build output (up to 500 chars) |
+| Blocked file violation | Ticket -> Failed with list of matched files and patterns. No code is pushed. |
 | Push fails | Ticket -> Failed, branch remains local |
 | PR creation fails | Ticket still moves to PR Ready (best-effort) |
 | Duplicate poll trigger | Skipped via in-memory lock per ticket ID |
@@ -612,6 +635,7 @@ Add to `projects.json` (or re-run `npx tsx index.ts init`):
 - **Read-only review** — the review agent cannot modify files. It only reads and analyzes.
 - **Sandboxed execution** — the execute agent has no access to the web, cannot push code, and cannot run destructive commands. TicketToPR handles git operations separately.
 - **Build gate** — code must pass your build validation before anything is pushed.
+- **Blocked file gate** — if `blockedFiles` patterns are configured, they're injected into both the review and execute agent prompts. A hard post-diff check also runs before push. Any violations abort the run — no code reaches origin.
 - **Human gate** — pull requests require your review and approval before merging.
 
 ## Tech Stack
@@ -626,6 +650,8 @@ Add to `projects.json` (or re-run `npx tsx index.ts init`):
 
 Contributions are welcome! Please open an issue first to discuss what you'd like to change.
 
+> **End users** should install via `npm install -g ticket-to-pr`. The instructions below are for contributors.
+
 ```bash
 git clone https://github.com/JohnRiceML/ticket-to-pr.git
 cd ticket-to-pr

package/dist/cli.js

@@ -1,9 +1,9 @@
 import { createInterface } from 'node:readline';
 import { execSync } from 'node:child_process';
-import { readFileSync, existsSync } from 'node:fs';
+import { readFileSync, existsSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { mask, shellEscape, writeEnvFile, updateProjectsFile } from './lib/utils.js';
-import { getProjectNames, getProjectDir } from './lib/projects.js';
+import { mask, shellEscape, writeEnvFile, updateProjectsFile, getDefaultBranch } from './lib/utils.js';
+import { getProjectNames, getProjectDir, getBaseBranch, getBlockedFiles, getSkipPR } from './lib/projects.js';
 import { CONFIG_DIR } from './lib/paths.js';
 // -- Colors --
 const RESET = '\x1b[0m';
@@ -27,6 +27,209 @@ function checkCommand(cmd) {
         return { ok: false, output: '' };
     }
 }
+function detectBuildCommand(dir) {
+    // Node.js — check package.json for build/test scripts
+    const pkgPath = join(dir, 'package.json');
+    if (existsSync(pkgPath)) {
+        try {
+            const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+            if (pkg.scripts?.build)
+                return 'npm run build';
+            if (pkg.scripts?.test)
+                return 'npm test';
+        }
+        catch { /* ignore parse errors */ }
+    }
+    // Rust
+    if (existsSync(join(dir, 'Cargo.toml')))
+        return 'cargo build';
+    // Go
+    if (existsSync(join(dir, 'go.mod')))
+        return 'go build ./...';
+    // Python
+    if (existsSync(join(dir, 'pyproject.toml')))
+        return 'python -m pytest';
+    // Makefile
+    if (existsSync(join(dir, 'Makefile')))
+        return 'make';
+    return undefined;
+}
+function detectProjectStack(dir) {
+    const stack = { language: 'JavaScript' };
+    // TypeScript detection
+    if (existsSync(join(dir, 'tsconfig.json'))) {
+        stack.language = 'TypeScript';
+    }
+    // Rust / Go / Python detection (override language)
+    if (existsSync(join(dir, 'Cargo.toml'))) {
+        stack.language = 'Rust';
+        stack.buildTool = 'cargo';
+        stack.testRunner = 'cargo test';
+        return stack;
+    }
+    if (existsSync(join(dir, 'go.mod'))) {
+        stack.language = 'Go';
+        stack.buildTool = 'go';
+        stack.testRunner = 'go test';
+        return stack;
+    }
+    if (existsSync(join(dir, 'pyproject.toml'))) {
+        stack.language = 'Python';
+        stack.testRunner = 'pytest';
+        return stack;
+    }
+    // Node.js ecosystem — read package.json for framework/tools
+    const pkgPath = join(dir, 'package.json');
+    if (existsSync(pkgPath)) {
+        try {
+            const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+            const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+            // Framework
+            if (allDeps['next'])
+                stack.framework = 'Next.js';
+            else if (allDeps['nuxt'])
+                stack.framework = 'Nuxt';
+            else if (allDeps['@remix-run/node'] || allDeps['@remix-run/react'])
+                stack.framework = 'Remix';
+            else if (allDeps['express'])
+                stack.framework = 'Express';
+            else if (allDeps['fastify'])
+                stack.framework = 'Fastify';
+            else if (allDeps['react'])
+                stack.framework = 'React';
+            else if (allDeps['vue'])
+                stack.framework = 'Vue';
+            else if (allDeps['svelte'])
+                stack.framework = 'Svelte';
+            // Test runner
+            if (allDeps['vitest'])
+                stack.testRunner = 'vitest';
+            else if (allDeps['jest'])
+                stack.testRunner = 'jest';
+            else if (allDeps['mocha'])
+                stack.testRunner = 'mocha';
+            // Build tool
+            if (allDeps['vite'] && !stack.framework?.includes('Next'))
+                stack.buildTool = 'vite';
+            else if (allDeps['webpack'])
+                stack.buildTool = 'webpack';
+            else if (allDeps['esbuild'])
+                stack.buildTool = 'esbuild';
+            else if (stack.language === 'TypeScript')
+                stack.buildTool = 'tsc';
+            // CSS
+            if (allDeps['tailwindcss'])
+                stack.css = 'Tailwind CSS';
+            // ORM
+            if (allDeps['prisma'] || allDeps['@prisma/client'])
+                stack.orm = 'Prisma';
+            else if (allDeps['drizzle-orm'])
+                stack.orm = 'Drizzle';
+        }
+        catch { /* ignore parse errors */ }
+    }
+    // Package manager
+    if (existsSync(join(dir, 'bun.lockb')))
+        stack.packageManager = 'bun';
+    else if (existsSync(join(dir, 'pnpm-lock.yaml')))
+        stack.packageManager = 'pnpm';
+    else if (existsSync(join(dir, 'yarn.lock')))
+        stack.packageManager = 'yarn';
+    else if (existsSync(join(dir, 'package-lock.json')))
+        stack.packageManager = 'npm';
+    return stack;
+}
+function generateClaudeMd(name, stack, buildCmd) {
+    const parts = [];
+    // Header
+    parts.push(`# ${name}\n`);
+    // Project overview
+    const stackDesc = [stack.language, stack.framework, stack.css, stack.orm].filter(Boolean).join(', ');
+    parts.push(`## Project overview`);
+    parts.push(`${stackDesc || stack.language} project.\n`);
+    // Build & test
+    parts.push(`## Build & test`);
+    if (buildCmd)
+        parts.push(`- Build: \`${buildCmd}\``);
+    if (stack.testRunner) {
+        const testCmd = stack.testRunner === 'vitest' ? 'npx vitest run'
+            : stack.testRunner === 'jest' ? 'npx jest'
+                : stack.testRunner === 'pytest' ? 'python -m pytest'
+                    : stack.testRunner === 'cargo test' ? 'cargo test'
+                        : stack.testRunner === 'go test' ? 'go test ./...'
+                            : stack.testRunner;
+        parts.push(`- Test: \`${testCmd}\``);
+    }
+    const pm = stack.packageManager || 'npm';
+    if (['TypeScript', 'JavaScript'].includes(stack.language)) {
+        parts.push(`- Lint: \`${pm === 'npm' ? 'npm run' : pm} lint\``);
+    }
+    if (stack.language === 'TypeScript') {
+        parts.push(`- Type check: \`npx tsc --noEmit\``);
+    }
+    parts.push('');
+    // Code style
+    parts.push(`## Code style`);
+    if (stack.framework === 'Next.js') {
+        parts.push(`- Use functional components with ${stack.language}`);
+        parts.push(`- Prefer server components; add "use client" only when needed`);
+    }
+    else if (stack.framework === 'React') {
+        parts.push(`- Use functional components with hooks`);
+    }
+    else if (stack.language === 'Rust') {
+        parts.push(`- Follow standard Rust conventions (rustfmt, clippy)`);
+    }
+    else if (stack.language === 'Go') {
+        parts.push(`- Follow standard Go conventions (gofmt, go vet)`);
+    }
+    else if (stack.language === 'Python') {
+        parts.push(`- Follow PEP 8 conventions`);
+    }
+    if (stack.css === 'Tailwind CSS') {
+        parts.push(`- Use Tailwind CSS utility classes for styling`);
+    }
+    if (stack.orm === 'Prisma') {
+        parts.push(`- Use Prisma for database access`);
+    }
+    else if (stack.orm === 'Drizzle') {
+        parts.push(`- Use Drizzle ORM for database access`);
+    }
+    parts.push('');
+    // File structure
+    parts.push(`## File structure`);
+    if (stack.framework === 'Next.js') {
+        parts.push(`- app/ — routes and layouts`);
+        parts.push(`- components/ — React components`);
+        parts.push(`- lib/ — utilities and shared logic`);
+        if (stack.orm === 'Prisma')
+            parts.push(`- prisma/ — database schema`);
+    }
+    else if (stack.framework === 'Express' || stack.framework === 'Fastify') {
+        parts.push(`- src/ — application source`);
+        parts.push(`- routes/ — API routes`);
+        parts.push(`- lib/ — utilities and shared logic`);
+    }
+    else if (stack.language === 'Rust') {
+        parts.push(`- src/ — application source`);
+        parts.push(`- tests/ — integration tests`);
+    }
+    else if (stack.language === 'Go') {
+        parts.push(`- cmd/ — entrypoints`);
+        parts.push(`- internal/ — private packages`);
+        parts.push(`- pkg/ — public packages`);
+    }
+    else if (stack.language === 'Python') {
+        parts.push(`- src/ — application source`);
+        parts.push(`- tests/ — test files`);
+    }
+    else {
+        parts.push(`- src/ — application source`);
+        parts.push(`- lib/ — utilities and shared logic`);
+    }
+    parts.push('');
+    return parts.join('\n');
+}
 function ask(rl, question, opts) {
     return new Promise((resolve) => {
         const suffix = opts?.defaultValue ? ` ${DIM}(${opts.defaultValue})${RESET}` : '';
@@ -275,6 +478,19 @@ export async function runDoctor() {
             }
             printStatus(true, `${name}`, `${dir}`);
             track(true);
+            // Display guardrail config
+            const configuredBase = getBaseBranch(name);
+            const detectedBase = getDefaultBranch(dir);
+            const baseDisplay = configuredBase
+                ? `${configuredBase}${configuredBase !== detectedBase ? ` (auto-detected: ${detectedBase})` : ''}`
+                : `${detectedBase} (auto-detected)`;
+            printStatus(null, `  Base branch`, baseDisplay);
+            const blocked = getBlockedFiles(name);
+            printStatus(null, `  Blocked files`, blocked.length > 0 ? blocked.join(', ') : 'none configured');
+            const skip = getSkipPR(name);
+            if (skip) {
+                printStatus(null, `  Skip PR`, 'enabled');
+            }
         }
     }
     // Summary
@@ -463,8 +679,39 @@ export async function runInit() {
             else {
                 printStatus(null, 'Not a git repo', `${dir} — you can init git later`);
             }
-            const buildCmd = await ask(rl, 'Build command (optional)');
-            projects.push({ name, dir, buildCmd: buildCmd || undefined });
+            const detectedBuild = detectBuildCommand(dir);
+            const buildCmd = await ask(rl, 'Build command' + (detectedBuild ? '' : ' (optional)'), {
+                defaultValue: detectedBuild,
+            });
+            // Detect default branch for this project
+            const gitExists2 = existsSync(join(dir, '.git'));
+            const detectedBranch = gitExists2 ? getDefaultBranch(dir) : 'main';
+            const baseBranchInput = await ask(rl, 'Base branch', { defaultValue: detectedBranch });
+            const baseBranch = baseBranchInput !== detectedBranch ? baseBranchInput : undefined;
+            console.log(`  ${DIM}Glob patterns the agent must never touch (e.g. **/migrations/**, prisma/schema.prisma, **/*.sql)${RESET}`);
+            const blockedInput = await ask(rl, 'Blocked file patterns (optional, comma-separated)');
+            const blockedFiles = blockedInput
+                ? blockedInput.split(',').map((s) => s.trim()).filter(Boolean)
+                : undefined;
+            const skipPRInput = await ask(rl, 'Skip automatic PR creation?', { defaultValue: 'N' });
+            const skipPR = skipPRInput.toLowerCase() === 'y' || skipPRInput.toLowerCase() === 'yes' ? true : undefined;
+            projects.push({ name, dir, buildCmd: buildCmd || undefined, baseBranch, blockedFiles, skipPR });
+            // Offer to generate CLAUDE.md if it doesn't exist
+            const claudeMdPath = join(dir, 'CLAUDE.md');
+            if (!existsSync(claudeMdPath)) {
+                const stack = detectProjectStack(dir);
+                console.log(`  ${DIM}Detected: ${[stack.language, stack.framework, stack.css, stack.orm].filter(Boolean).join(', ')}${RESET}`);
+                const genClaudeMd = await ask(rl, 'Generate starter CLAUDE.md?', { defaultValue: 'Y' });
+                if (genClaudeMd.toLowerCase() === 'y' || genClaudeMd.toLowerCase() === 'yes') {
+                    const content = generateClaudeMd(name, stack, buildCmd || undefined);
+                    writeFileSync(claudeMdPath, content, 'utf-8');
+                    printStatus(true, 'Generated CLAUDE.md', claudeMdPath);
+                    console.log(`  ${DIM}Edit it to add project-specific rules and conventions.${RESET}`);
+                }
+            }
+            else {
+                printStatus(true, 'CLAUDE.md exists', claudeMdPath);
+            }
             console.log('');
             const another = await ask(rl, 'Add another project?', { defaultValue: 'N' });
             addMore = another.toLowerCase() === 'y' || another.toLowerCase() === 'yes';

package/dist/index.js

@@ -3,8 +3,8 @@ import { execSync } from 'node:child_process';
 import { join } from 'node:path';
 import { query } from '@anthropic-ai/claude-agent-sdk';
 import { CONFIG, REVIEW_OUTPUT_SCHEMA, isPro } from './config.js';
-import { sleep, clamp, extractJsonFromOutput, shellEscape, extractNumber, loadEnv, createWorktree, removeWorktree, getDefaultBranch } from './lib/utils.js';
-import { getProjectDir, getProjectNames, getBuildCommand } from './lib/projects.js';
+import { sleep, clamp, extractJsonFromOutput, shellEscape, extractNumber, loadEnv, createWorktree, removeWorktree, getDefaultBranch, validateNoBlockedFiles } from './lib/utils.js';
+import { getProjectDir, getProjectNames, getBuildCommand, getBaseBranch, getBlockedFiles, getSkipPR } from './lib/projects.js';
 import { fetchTicketsByStatus, fetchTicketDetails, writeReviewResults, writeExecutionResults, moveTicketStatus, writeFailure, addComment, } from './lib/notion.js';
 import { PACKAGE_ROOT, CONFIG_DIR } from './lib/paths.js';
 // Load .env.local from the user's working directory
@@ -51,7 +51,8 @@ async function runReviewAgent(ticket) {
     }
     log(CYAN, 'REVIEW', `Starting review for "${ticket.title}" in ${ticket.project}`);
     const startTime = Date.now();
-    const prompt = [
+    const blockedFiles = getBlockedFiles(ticket.project);
+    const promptParts = [
         reviewPrompt,
         '',
         '## Ticket',
@@ -62,7 +63,11 @@ async function runReviewAgent(ticket) {
         '',
         '**Page Content**:',
         ticket.bodyBlocks,
-    ].join('\n');
+    ];
+    if (blockedFiles.length > 0) {
+        promptParts.push('', '## BLOCKED FILES — CANNOT BE MODIFIED', 'The following file patterns are off-limits. Factor this into your scoring — if the natural implementation would touch these files, lower the ease and confidence scores and note it in risks.', '', ...blockedFiles.map(p => `- \`${p}\``));
+    }
+    const prompt = promptParts.join('\n');
     const messages = query({
         prompt,
         options: {
@@ -157,16 +162,20 @@ async function runExecuteAgent(ticket) {
         .slice(0, 40);
     const branchName = `notion/${shortId}/${slug}`;
     const worktreeDir = join(projectDir, '.worktrees', branchName.replace(/\//g, '_'));
+    // Resolve per-project guardrails
+    const baseBranch = getBaseBranch(ticket.project) || getDefaultBranch(projectDir);
+    const blockedFiles = getBlockedFiles(ticket.project);
+    const skipPR = getSkipPR(ticket.project);
     log(MAGENTA, 'EXECUTE', `Starting execution for "${ticket.title}" on branch ${branchName}`);
     const startTime = Date.now();
     // Move to In Progress immediately
     await moveTicketStatus(ticket.id, CONFIG.COLUMNS.IN_PROGRESS);
-    // Git: create isolated worktree
-    createWorktree(projectDir, branchName, worktreeDir);
+    // Git: create isolated worktree (fetches origin/<baseBranch> first)
+    createWorktree(projectDir, branchName, worktreeDir, baseBranch);
     let cost = 0;
     let commitCount = 0;
     try {
-        const prompt = [
+        const promptParts = [
             executePrompt,
             '',
             '## Ticket',
@@ -183,7 +192,11 @@ async function runExecuteAgent(ticket) {
             '',
             '**Page Content**:',
             ticket.bodyBlocks,
-        ].join('\n');
+        ];
+        if (blockedFiles.length > 0) {
+            promptParts.push('', '## BLOCKED FILES — DO NOT TOUCH', 'The following file patterns are off-limits. Do NOT create, modify, or delete any files matching these patterns. Violations will cause the entire run to fail.', '', ...blockedFiles.map((p) => `- \`${p}\``));
+        }
+        const prompt = promptParts.join('\n');
         const messages = query({
             prompt,
             options: {
@@ -216,7 +229,6 @@ async function runExecuteAgent(ticket) {
             }
         }
         // Count commits made
-        const baseBranch = getDefaultBranch(projectDir);
         try {
             const commitLog = execSync(`git log ${shellEscape(baseBranch)}..${shellEscape(branchName)} --oneline`, { cwd: worktreeDir, stdio: 'pipe' });
             commitCount = commitLog.toString().trim().split('\n').filter(Boolean).length;
@@ -246,36 +258,49 @@ async function runExecuteAgent(ticket) {
                 throw new Error(`Build validation failed.\nCommand: ${buildCmd}\nDirectory: ${worktreeDir}\n${detail ? `Output:\n${detail}` : (e instanceof Error ? e.message : String(e))}`);
             }
         }
+        // Post-execution: validate no blocked files were touched
+        if (blockedFiles.length > 0) {
+            const violations = validateNoBlockedFiles(worktreeDir, baseBranch, blockedFiles);
+            if (violations.length > 0) {
+                throw new Error(`Blocked file violation — the agent modified files that are off-limits:\n${violations.map((v) => `  - ${v}`).join('\n')}\n\nNo code was pushed. Fix the blocked file patterns in projects.json or adjust the ticket scope.`);
+            }
+            log(GREEN, 'VALIDATE', 'No blocked file violations');
+        }
         // Push branch
         log(CYAN, 'PUSH', `Pushing ${branchName}`);
         execSync(`git push -u origin ${shellEscape(branchName)}`, { cwd: worktreeDir, stdio: 'pipe' });
-        // Create PR
+        // Create PR (unless skipPR is configured)
         let prUrl = '';
-        try {
-            log(CYAN, 'PR', 'Creating pull request...');
-            const prBody = [
-                '## Summary',
-                '',
-                ticket.spec ?? ticket.description,
-                '',
-                '## Impact',
-                '',
-                ticket.impact ?? '_No impact analysis_',
-                '',
-                `## Notion Ticket`,
-                '',
-                `[View in Notion](https://www.notion.so/${ticket.id.replace(/-/g, '')})`,
-                '',
-                '---',
-                `Cost: $${cost.toFixed(2)} | Review: Ease ${extractNumber(ticket, 'ease')}/10, Confidence ${extractNumber(ticket, 'confidence')}/10`,
-            ].join('\n');
-            const prResult = execSync(`gh pr create --title ${shellEscape(ticket.title)} --body ${shellEscape(prBody)} --base ${shellEscape(baseBranch)} --head ${branchName}`, { cwd: worktreeDir, stdio: 'pipe', timeout: 30_000 });
-            prUrl = prResult.toString().trim();
-            log(GREEN, 'PR', `Created: ${prUrl}`);
+        if (skipPR) {
+            log(YELLOW, 'PR', 'Skipping PR creation (skipPR enabled for this project)');
         }
-        catch (e) {
-            // PR creation is best-effort — don't fail the ticket over it
-            log(YELLOW, 'PR', `Failed to create PR: ${e instanceof Error ? e.message : e}`);
+        else {
+            try {
+                log(CYAN, 'PR', 'Creating pull request...');
+                const prBody = [
+                    '## Summary',
+                    '',
+                    ticket.spec ?? ticket.description,
+                    '',
+                    '## Impact',
+                    '',
+                    ticket.impact ?? '_No impact analysis_',
+                    '',
+                    `## Notion Ticket`,
+                    '',
+                    `[View in Notion](https://www.notion.so/${ticket.id.replace(/-/g, '')})`,
+                    '',
+                    '---',
+                    `Cost: $${cost.toFixed(2)} | Review: Ease ${extractNumber(ticket, 'ease')}/10, Confidence ${extractNumber(ticket, 'confidence')}/10`,
+                ].join('\n');
+                const prResult = execSync(`gh pr create --title ${shellEscape(ticket.title)} --body ${shellEscape(prBody)} --base ${shellEscape(baseBranch)} --head ${branchName}`, { cwd: worktreeDir, stdio: 'pipe', timeout: 30_000 });
+                prUrl = prResult.toString().trim();
+                log(GREEN, 'PR', `Created: ${prUrl}`);
+            }
+            catch (e) {
+                // PR creation is best-effort — don't fail the ticket over it
+                log(YELLOW, 'PR', `Failed to create PR: ${e instanceof Error ? e.message : e}`);
+            }
         }
         // Update Notion
         await writeExecutionResults(ticket.id, { branch: branchName, cost, prUrl });

package/dist/lib/projects.d.ts

@@ -1,6 +1,9 @@
 export declare function getProjectDir(name: string): string | undefined;
 export declare function getProjectNames(): string[];
 export declare function getBuildCommand(name: string): string | undefined;
+export declare function getBaseBranch(name: string): string | undefined;
+export declare function getBlockedFiles(name: string): string[];
+export declare function getSkipPR(name: string): boolean;
 export declare function getAllProjects(): Record<string, string>;
 /** Reset the in-memory cache (for tests). */
 export declare function _resetCache(): void;

package/dist/lib/projects.js

@@ -24,6 +24,15 @@ export function getProjectNames() {
 export function getBuildCommand(name) {
     return load().projects[name]?.buildCommand;
 }
+export function getBaseBranch(name) {
+    return load().projects[name]?.baseBranch;
+}
+export function getBlockedFiles(name) {
+    return load().projects[name]?.blockedFiles ?? [];
+}
+export function getSkipPR(name) {
+    return load().projects[name]?.skipPR ?? false;
+}
 export function getAllProjects() {
     const data = load();
     const result = {};

package/dist/lib/utils.d.ts

@@ -12,10 +12,14 @@ export declare function updateProjectsFile(filepath: string, projects: Array<{
     name: string;
     dir: string;
     buildCmd?: string;
+    baseBranch?: string;
+    blockedFiles?: string[];
+    skipPR?: boolean;
 }>): void;
 export declare function getDefaultBranch(projectDir: string): string;
 /** Reset the default branch cache (for tests). */
 export declare function _resetDefaultBranchCache(): void;
 export declare function ensureWorktreesIgnored(projectDir: string): void;
-export declare function createWorktree(projectDir: string, branchName: string, worktreeDir: string): void;
+export declare function createWorktree(projectDir: string, branchName: string, worktreeDir: string, baseBranch?: string): void;
+export declare function validateNoBlockedFiles(worktreeDir: string, baseBranch: string, blockedPatterns: string[]): string[];
 export declare function removeWorktree(projectDir: string, worktreeDir: string): void;

package/dist/lib/utils.js

@@ -133,6 +133,9 @@ export function updateProjectsFile(filepath, projects) {
         data.projects[proj.name] = {
             directory: proj.dir,
             ...(proj.buildCmd ? { buildCommand: proj.buildCmd } : {}),
+            ...(proj.baseBranch ? { baseBranch: proj.baseBranch } : {}),
+            ...(proj.blockedFiles && proj.blockedFiles.length > 0 ? { blockedFiles: proj.blockedFiles } : {}),
+            ...(proj.skipPR ? { skipPR: proj.skipPR } : {}),
         };
     }
     writeFileSync(filepath, JSON.stringify(data, null, 2) + '\n');
@@ -193,9 +196,19 @@ export function ensureWorktreesIgnored(projectDir) {
         // Best effort — don't block worktree creation over gitignore
     }
 }
-export function createWorktree(projectDir, branchName, worktreeDir) {
+export function createWorktree(projectDir, branchName, worktreeDir, baseBranch) {
     mkdirSync(join(projectDir, '.worktrees'), { recursive: true });
     ensureWorktreesIgnored(projectDir);
+    // Fetch latest so new branch starts from up-to-date base
+    const base = baseBranch || 'main';
+    try {
+        execSync(`git fetch origin ${shellEscape(base)}`, {
+            cwd: projectDir, stdio: 'pipe', timeout: 30_000,
+        });
+    }
+    catch {
+        // Best effort — offline/no remote continues with local state
+    }
     // Clean up stale worktree if it exists from a crashed run
     if (existsSync(worktreeDir)) {
         try {
@@ -209,9 +222,9 @@ export function createWorktree(projectDir, branchName, worktreeDir) {
             execSync('git worktree prune', { cwd: projectDir, stdio: 'pipe' });
         }
     }
-    // Try creating with a new branch first
+    // Try creating with a new branch based on origin/<baseBranch>
     try {
-        execSync(`git worktree add ${shellEscape(worktreeDir)} -b ${shellEscape(branchName)}`, {
+        execSync(`git worktree add ${shellEscape(worktreeDir)} -b ${shellEscape(branchName)} origin/${shellEscape(base)}`, {
             cwd: projectDir,
             stdio: 'pipe',
         });
@@ -229,6 +242,73 @@ export function createWorktree(projectDir, branchName, worktreeDir) {
         }
     }
 }
+// -- Blocked file validation --
+/** Convert a simple glob pattern to a regex. Supports **, *, and ? wildcards. */
+function globToRegex(pattern) {
+    let regex = '';
+    let i = 0;
+    while (i < pattern.length) {
+        const ch = pattern[i];
+        if (ch === '*' && pattern[i + 1] === '*') {
+            // ** matches any path segments
+            regex += '.*';
+            i += 2;
+            // skip trailing slash after **
+            if (pattern[i] === '/')
+                i++;
+        }
+        else if (ch === '*') {
+            // * matches anything except /
+            regex += '[^/]*';
+            i++;
+        }
+        else if (ch === '?') {
+            regex += '[^/]';
+            i++;
+        }
+        else if ('.+^${}()|[]\\'.includes(ch)) {
+            regex += '\\' + ch;
+            i++;
+        }
+        else {
+            regex += ch;
+            i++;
+        }
+    }
+    return new RegExp(`^${regex}$`);
+}
+export function validateNoBlockedFiles(worktreeDir, baseBranch, blockedPatterns) {
+    if (blockedPatterns.length === 0)
+        return [];
+    let changedFiles;
+    try {
+        const output = execSync(`git diff --name-only origin/${shellEscape(baseBranch)}...HEAD`, { cwd: worktreeDir, stdio: 'pipe' }).toString().trim();
+        changedFiles = output ? output.split('\n') : [];
+    }
+    catch {
+        // Fallback: diff against HEAD~1 or empty if no commits
+        try {
+            const output = execSync('git diff --name-only HEAD~1...HEAD', {
+                cwd: worktreeDir, stdio: 'pipe',
+            }).toString().trim();
+            changedFiles = output ? output.split('\n') : [];
+        }
+        catch {
+            return []; // No commits to validate
+        }
+    }
+    const regexes = blockedPatterns.map(globToRegex);
+    const violations = [];
+    for (const file of changedFiles) {
+        for (let i = 0; i < regexes.length; i++) {
+            if (regexes[i].test(file)) {
+                violations.push(`${file} (matched pattern: ${blockedPatterns[i]})`);
+                break;
+            }
+        }
+    }
+    return violations;
+}
 export function removeWorktree(projectDir, worktreeDir) {
     try {
         execSync(`git worktree remove ${shellEscape(worktreeDir)} --force`, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ticket-to-pr",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Drag a Notion ticket, get a pull request. AI-powered dev automation.",
   "type": "module",
   "bin": {

package/projects.example.json

@@ -2,7 +2,10 @@
   "projects": {
     "MyProject": {
       "directory": "/absolute/path/to/project",
-      "buildCommand": "npm run build"
+      "buildCommand": "npm run build",
+      "baseBranch": "develop",
+      "blockedFiles": ["**/migrations/**", "prisma/schema.prisma", "**/*.sql"],
+      "skipPR": false
     }
   }
 }

package/prompts/execute.md

@@ -14,6 +14,7 @@ You have been given a ticket with an implementation spec. Follow the spec and im
 8. If the spec is unclear, implement the most conservative interpretation.
 9. Run existing tests if available, but do not add new test files unless the spec explicitly requires it.
 10. Do not modify files outside the scope of the spec.
+11. If your prompt includes a "BLOCKED FILES" section, you MUST NOT modify any files matching those patterns. Violations will cause the entire run to fail.
 
 ## When Done
 Commit all changes with a final commit message summarizing what was done. The commit message should reference the ticket title.

package/prompts/review.md

@@ -41,3 +41,4 @@ You MUST end your response with a JSON code block containing exactly these field
 - List EVERY file that will be touched in affectedFiles.
 - Read the project's CLAUDE.md if it exists for project-specific rules and architecture.
 - Explore relevant code files to understand existing patterns before scoring.
+- If the prompt includes a "BLOCKED FILES" section, factor those constraints into your scoring. If the natural implementation would need to modify blocked files, lower the ease score and note the constraint in risks.