stet-cli 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.2.0 — 2026-11-14
+- New `stet pr`: writes the commit message and PR description from facts — the diff since the scope was set, the ticket ID, scope result, `stet check` results and decisions logged during the task. `--check` runs the locks first, `--base main` compares against a branch.
+- Ticket IDs: `stet scope set "LIN-142 Add CSV export" …` (or `--ticket LIN-142`) stores the ticket. It appears in AGENTS.md, context packs, guard output and PR text.
+- `stet hook install` now also adds a prepare-commit-msg hook that prefixes commit messages with the ticket ID ("LIN-142: …"), never twice.
+- New MCP tool `stet_pr` so Claude Code and Cursor can draft the PR text.
+- The pre-commit hook falls back to `npx stet-cli` when stet isn't installed globally.
+
+## 0.1.3 — 2026-11-14
+- Stack detection now finds projects in subfolders (e.g. backend/, frontend/, apps/web) and languages from file types, so monorepos with Python + JavaScript are detected correctly.
+- stet init creates one test lock per sub-project (e.g. `cd backend && pytest -q`).
+
 ## 0.1.2 — 2026-11-13
 - Published on npm as stet-cli (the command is still `stet`).
 

package/README.md

@@ -9,6 +9,7 @@ Stet is a small, free command-line tool that gives every AI coding tool (Claude
 - **Scope guard.** Agree the task and the files it may touch. `stet guard` flags every file changed outside scope or in protected paths, even if the agent already committed it.
 - **Git-synced context.** `stet context` builds a context pack from the live repo (charter, scope, locks, decisions, commits, uncommitted changes, file tree and the files you choose). Paste it into any chat instead of uploading your `src` folder.
 - **Decision log.** `stet decide` records "we chose X because Y", so the next session doesn't reopen it.
+- **Ticket-aware PRs.** Put the ticket ID in the scope (`LIN-142 Add CSV export`) and `stet pr` writes the commit message and PR description from the real diff, scope, check results and decisions. The git hook adds the ticket ID to every commit.
 - **Handoff pack.** `stet handoff` writes an onboarding document for a new developer or CTO, built from the repo.
 - **MCP server.** `stet mcp` exposes all of this as tools to Claude Code, Cursor and any MCP client.
 
@@ -43,13 +44,17 @@ Commit `.stet/`, `AGENTS.md` and `CLAUDE.md`. Every agent and teammate then work
 # once: lock what already works
 stet lock add "UAE VAT maths is correct" --cmd "node --test test/vat.test.js" --protect "src/vat/**"
 
-# before each AI task
-stet scope set "Add CSV export of invoices" --allow "src/export/**,test/export*"
+# before each AI task (the ticket ID is optional)
+stet scope set "LIN-142 Add CSV export of invoices" --allow "src/export/**,test/export*"
 stet context --files "src/invoices/**"     # copied to clipboard; paste into your chat
 
 # after the AI says it's done
 stet guard        # anything outside scope or in protected paths?
 stet check        # do all locked behaviours still pass?
+
+# ship it
+stet pr                                   # commit message + PR description (PR copied to clipboard)
+git commit -F .stet/.cache/commit.txt     # "LIN-142: Add CSV export of invoices" + file list
 ```
 
 Example (real output from a sample accounting app):
@@ -81,8 +86,8 @@ Checking 2 locked behaviours
 |---|---|
 | `stet init [--name X] [--mcp]` | Set up `.stet/`, `AGENTS.md` and `CLAUDE.md`. `--mcp` also writes `.mcp.json`. Safe to re-run. |
 | `stet sync` | Regenerate the Stet block in `AGENTS.md` (other commands do this automatically). |
-| `stet scope set "<task>" --allow "<globs>"` | Agree the task and the files it may touch. Records the current commit as the base. |
-| `stet scope [show\|clear]` | Show or clear the scope. |
+| `stet scope set "<task>" --allow "<globs>" [--ticket LIN-142]` | Agree the task and the files it may touch. Records the current commit as the base. A ticket ID at the start of the task is picked up automatically. |
+| `stet scope [show\|clear\|ticket]` | Show or clear the scope, or print just the ticket ID. |
 | `stet guard [--staged] [--base ref] [--warn]` | Check changes since the scope base (committed, staged, unstaged and untracked). Exits 1 on violations unless `--warn`. |
 | `stet lock add "<behaviour>" --cmd "<cmd>" [--protect "<globs>"]` | Lock a behaviour. `--protect` tells guard which files affect it. |
 | `stet lock [list\|rm L2]` | List locks with their last result, or remove one. |
@@ -90,8 +95,9 @@ Checking 2 locked behaviours
 | `stet context [--files "<globs>"] [--changed] [--diff] [--copy\|--stdout\|--out f]` | Build the context pack. By default it writes `.stet/context.md` and copies it to the clipboard. |
 | `stet decide "<decision>" [--why "<reason>"]` | Add to the decision log. |
 | `stet decisions [--all]` | List decisions. |
+| `stet pr [--base main] [--check] [--stdout]` | Write `.stet/.cache/commit.txt` and `.stet/.cache/pr.md` from the diff since the scope was set: ticket, changed files, scope result, `stet check` results and decisions logged during the task. `--check` runs the locks first. |
 | `stet handoff [--out HANDOFF.md] [--stdout]` | Generate the onboarding pack. |
-| `stet hook install [--check]` | Add a git pre-commit hook that blocks commits staging out-of-scope or protected files. `--check` also runs `stet check`. |
+| `stet hook install [--check]` | Add git hooks: pre-commit blocks commits that stage out-of-scope or protected files (`--check` also runs `stet check`); prepare-commit-msg adds the ticket ID to commit messages. |
 | `stet status` | One-screen summary. |
 | `stet mcp` / `stet mcp install` | Run the MCP server over stdio, or write `.mcp.json`. |
 
@@ -111,7 +117,7 @@ Add `--json` to any command for machine-readable output.
 
 **ChatGPT, Claude.ai, Gemini (chat):** run `stet context --files "<what you're working on>"` and paste the result.
 
-MCP tools: `stet_context`, `stet_guard`, `stet_check`, `stet_scope` (read-only; only the human sets scope) and `stet_decide`.
+MCP tools: `stet_context`, `stet_guard`, `stet_check`, `stet_scope` (read-only; only the human sets scope), `stet_pr` and `stet_decide`.
 
 ## Configuration
 

package/bin/stet.js

@@ -28,8 +28,9 @@ ${c.bold('Setup')}
   stet sync                           Regenerate AGENTS.md from .stet/
 
 ${c.bold('Before an AI task')}
-  stet scope set "<task>" --allow "src/x/**,tests/x/**"
-  stet scope [show|clear]
+  stet scope set "<task>" --allow "src/x/**,tests/x/**" [--ticket LIN-142]
+                                      A ticket ID at the start of the task ("LIN-142 Add export") is picked up too
+  stet scope [show|clear|ticket]
   stet context [--files "glob,glob"] [--changed] [--diff] [--copy|--stdout|--out file]
                                       Git-synced context pack for any AI chat (no more uploading src/)
 
@@ -37,6 +38,11 @@ ${c.bold('After an AI task')}
   stet guard [--staged] [--base ref] [--warn]   Flag changes outside scope or in protected paths
   stet check [--only L1,L2]                      Run locked behaviours; non-zero exit if any broke
 
+${c.bold('Shipping')}
+  stet pr [--base main] [--check] [--stdout]
+                                      Commit message + PR description from the diff, scope, checks and decisions
+                                      Then: git commit -F .stet/.cache/commit.txt
+
 ${c.bold('Memory')}
   stet lock add "<behaviour>" --cmd "<proof command>" [--protect "glob,glob"]
   stet lock [list|rm L2]
@@ -77,9 +83,10 @@ function main() {
     case 'check': res = core.check(r, { only: fl.only }); break;
     case 'scope':
       if (!sub || sub === 'show') res = core.scopeShow(r);
-      else if (sub === 'set') res = core.scopeSet(r, rest.join(' '), { allow: fl.allow });
+      else if (sub === 'set') res = core.scopeSet(r, rest.join(' '), { allow: fl.allow, ticket: fl.ticket });
+      else if (sub === 'ticket') res = core.scopeTicket(r);
       else if (sub === 'clear') res = core.scopeClear(r);
-      else throw new core.StetError('Usage: stet scope [show|set|clear]');
+      else throw new core.StetError('Usage: stet scope [show|set|clear|ticket]');
       break;
     case 'guard': res = core.guard(r, { staged: fl.staged, base: fl.base, warn: fl.warn }); break;
     case 'context': case 'ctx': {
@@ -102,6 +109,25 @@ function main() {
       res = { code: 0, text: `${c.green('✓')} Handoff pack written to ${c.bold(path.relative(process.cwd(), file) || file)}` };
       break;
     }
+    case 'pr': {
+      core.setColor(false);
+      const p = core.pr(r, { base: fl.base, runCheck: fl.check });
+      core.setColor((process.stdout.isTTY || process.env.STET_COLOR === '1') && !process.env.NO_COLOR && !fl['no-color']);
+      if (fl.stdout) { process.stdout.write(p.text); return; }
+      const copied = core.copyToClipboard(p.data.pr);
+      const warn = [];
+      if (p.data.violations.length) warn.push(c.yellow(`! ${p.data.violations.length} file(s) outside scope or protected — listed in the PR text.`));
+      if (!p.data.checks) warn.push(c.yellow('! stet check has not been run for this change. Run it, or use stet pr --check.'));
+      else if (p.data.checks.some((x) => !x.ok)) warn.push(c.red('✗ A locked behaviour is failing — listed in the PR text.'));
+      res = { code: 0, text: [
+        `${c.green('✓')} ${c.bold(p.data.title)}  ${c.dim(`(${p.data.files} files)`)}`,
+        `  commit message  .stet/.cache/commit.txt   →  ${c.cyan('git commit -F .stet/.cache/commit.txt')}`,
+        `  PR description  .stet/.cache/pr.md        →  ${copied ? 'copied to clipboard' : 'open the file, or run: stet pr --stdout'}`,
+        ...warn.map((w) => '  ' + w),
+        c.dim('  Fill in the "What and why" line (or paste the PR text into your AI and ask it to write it).'),
+      ].join('\n') };
+      break;
+    }
     case 'status': case 'st': res = core.status(r); break;
     case 'hook':
       if (sub === 'install') res = core.hook(r, { withCheck: fl.check });

package/lib/core.js

@@ -77,37 +77,83 @@ function matches(file, globs) {
 const splitList = (v) => (Array.isArray(v) ? v : String(v || '').split(',')).map((s) => s.trim()).filter(Boolean);
 
 // ---------- stack detection ----------
-function detect(root) {
-  const ex = (f) => fs.existsSync(path.join(root, f));
-  const rd = (f) => { try { return fs.readFileSync(path.join(root, f), 'utf8'); } catch { return ''; } };
-  const s = { langs: [], frameworks: [], test: null, run: [], deps: [], entry: [] };
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.next', 'out', 'coverage', '__pycache__', '.venv', 'venv', 'env', 'vendor', 'target', '.stet', '.idea', '.vscode']);
+const MANIFESTS = ['package.json', 'pyproject.toml', 'requirements.txt', 'setup.py', 'Pipfile', 'go.mod', 'Cargo.toml', 'Gemfile', 'pom.xml', 'build.gradle', 'composer.json', 'pubspec.yaml'];
+const EXT_LANG = { py: 'Python', ts: 'TypeScript', tsx: 'TypeScript', js: 'JavaScript', jsx: 'JavaScript', go: 'Go', rs: 'Rust', rb: 'Ruby', java: 'Java', kt: 'Kotlin', swift: 'Swift', php: 'PHP', cs: 'C#', dart: 'Dart' };
+
+// Folders (root + up to 2 levels deep) that contain a project manifest, e.g. "", "backend", "apps/web".
+function projectDirs(root) {
+  const out = [];
+  const walk = (rel, depth) => {
+    const abs = path.join(root, rel);
+    let entries = [];
+    try { entries = fs.readdirSync(abs, { withFileTypes: true }); } catch { return; }
+    if (entries.some((e) => e.isFile() && MANIFESTS.includes(e.name))) out.push(rel);
+    if (depth >= 2) return;
+    for (const e of entries) if (e.isDirectory() && !SKIP_DIRS.has(e.name) && !e.name.startsWith('.')) walk(rel ? rel + '/' + e.name : e.name, depth + 1);
+  };
+  walk('', 0);
+  return out;
+}
+
+function detectIn(root, rel, s) {
+  const ex = (f) => fs.existsSync(path.join(root, rel, f));
+  const rd = (f) => { try { return fs.readFileSync(path.join(root, rel, f), 'utf8'); } catch { return ''; } };
+  const where = rel ? ` (${rel}/)` : '';
+  const cd = (cmd) => (rel ? `cd ${rel} && ${cmd}` : cmd);
+  const addLang = (l) => { if (!s.langs.includes(l + where)) s.langs.push(l + where); };
+  const addFw = (f) => { if (!s.frameworks.includes(f)) s.frameworks.push(f); };
+  const addTest = (cmd) => { if (!s.tests.includes(cd(cmd))) s.tests.push(cd(cmd)); };
+  const p = (f) => (rel ? rel + '/' + f : f);
   if (ex('package.json')) {
     let pj = {}; try { pj = JSON.parse(rd('package.json')); } catch {}
     const deps = { ...(pj.dependencies || {}), ...(pj.devDependencies || {}) };
     s.deps.push(...Object.keys(pj.dependencies || {}));
-    s.langs.push(deps.typescript || ex('tsconfig.json') ? 'TypeScript' : 'JavaScript');
-    for (const [k, n] of [['next', 'Next.js'], ['react', 'React'], ['vue', 'Vue'], ['svelte', 'Svelte'], ['express', 'Express'], ['@nestjs/core', 'NestJS'], ['fastify', 'Fastify'], ['hono', 'Hono'], ['vite', 'Vite'], ['prisma', 'Prisma'], ['drizzle-orm', 'Drizzle'], ['@supabase/supabase-js', 'Supabase'], ['stripe', 'Stripe'], ['tailwindcss', 'Tailwind']]) if (deps[k]) s.frameworks.push(n);
-    const pm = ex('pnpm-lock.yaml') ? 'pnpm' : ex('yarn.lock') ? 'yarn' : ex('bun.lockb') || ex('bun.lock') ? 'bun' : 'npm';
+    const emptyWorkspaceRoot = !rel && !Object.keys(deps).length && !Object.keys(pj.scripts || {}).length;
+    if (!emptyWorkspaceRoot) addLang(deps.typescript || ex('tsconfig.json') ? 'TypeScript' : 'JavaScript');
+    for (const [k, n] of [['next', 'Next.js'], ['react', 'React'], ['vue', 'Vue'], ['svelte', 'Svelte'], ['express', 'Express'], ['@nestjs/core', 'NestJS'], ['fastify', 'Fastify'], ['hono', 'Hono'], ['vite', 'Vite'], ['prisma', 'Prisma'], ['drizzle-orm', 'Drizzle'], ['@supabase/supabase-js', 'Supabase'], ['stripe', 'Stripe'], ['tailwindcss', 'Tailwind']]) if (deps[k]) addFw(n);
+    const rootEx = (f) => ex(f) || fs.existsSync(path.join(root, f));
+    const pm = rootEx('pnpm-lock.yaml') ? 'pnpm' : rootEx('yarn.lock') ? 'yarn' : rootEx('bun.lockb') || rootEx('bun.lock') ? 'bun' : 'npm';
     const sc = pj.scripts || {};
-    if (sc.test && !/no test specified/.test(sc.test)) s.test = `${pm} test`;
-    for (const k of ['dev', 'start', 'build', 'lint', 'typecheck']) if (sc[k]) s.run.push(`${pm} run ${k}`);
-    if (pj.main) s.entry.push(pj.main);
-    if (pj.bin) s.entry.push(...(typeof pj.bin === 'string' ? [pj.bin] : Object.values(pj.bin)));
+    if (sc.test && !/no test specified/.test(sc.test)) addTest(`${pm} test`);
+    for (const k of ['dev', 'start', 'build', 'lint', 'typecheck']) if (sc[k]) s.run.push(cd(`${pm} run ${k}`));
+    if (pj.main) s.entry.push(p(pj.main));
+    if (pj.bin) s.entry.push(...(typeof pj.bin === 'string' ? [pj.bin] : Object.values(pj.bin)).map(p));
+  }
+  if (ex('pyproject.toml') || ex('requirements.txt') || ex('setup.py') || ex('Pipfile')) {
+    addLang('Python');
+    const txt = (rd('pyproject.toml') + '\n' + rd('requirements.txt') + '\n' + rd('Pipfile')).toLowerCase();
+    for (const [k, n] of [['django', 'Django'], ['fastapi', 'FastAPI'], ['flask', 'Flask'], ['sqlalchemy', 'SQLAlchemy'], ['pydantic', 'Pydantic'], ['pandas', 'pandas'], ['celery', 'Celery']]) if (txt.includes(k)) addFw(n);
+    s.deps.push(...nonEmpty(rd('requirements.txt')).filter((l) => !l.trim().startsWith('#') && !l.trim().startsWith('-')).map((l) => l.trim().split(/[=<>~! ;\[]/)[0]));
+    if (ex('tests') || ex('test') || ex('pytest.ini') || ex('conftest.py') || txt.includes('[tool.pytest')) addTest('pytest -q');
+    if (ex('manage.py')) { s.run.push(cd('python manage.py runserver')); s.entry.push(p('manage.py')); }
   }
-  if (ex('pyproject.toml') || ex('requirements.txt') || ex('setup.py')) {
-    s.langs.push('Python');
-    const txt = (rd('pyproject.toml') + '\n' + rd('requirements.txt')).toLowerCase();
-    for (const [k, n] of [['django', 'Django'], ['fastapi', 'FastAPI'], ['flask', 'Flask'], ['sqlalchemy', 'SQLAlchemy'], ['pydantic', 'Pydantic'], ['pandas', 'pandas'], ['celery', 'Celery']]) if (txt.includes(k)) s.frameworks.push(n);
-    s.deps.push(...nonEmpty(rd('requirements.txt')).filter((l) => !l.startsWith('#')).map((l) => l.split(/[=<>~! ;\[]/)[0]));
-    if (!s.test && (ex('tests') || ex('pytest.ini') || txt.includes('pytest'))) s.test = 'pytest -q';
-    if (ex('manage.py')) { s.run.push('python manage.py runserver'); s.entry.push('manage.py'); }
+  if (ex('go.mod')) { addLang('Go'); addTest('go test ./...'); }
+  if (ex('Cargo.toml')) { addLang('Rust'); addTest('cargo test'); }
+  if (ex('Gemfile')) addLang('Ruby');
+  if (ex('pom.xml') || ex('build.gradle')) addLang('Java');
+  if (ex('composer.json')) addLang('PHP');
+  if (ex('pubspec.yaml')) addLang('Dart');
+  if (ex('Dockerfile') || ex('docker-compose.yml') || ex('docker-compose.yaml') || ex('compose.yaml')) addFw('Docker');
+  for (const f of ['main.py', 'app.py', 'server.js', 'index.js', 'src/server.js', 'src/server.ts', 'src/app.js', 'src/index.ts', 'src/main.ts', 'src/index.js', 'src/app.ts', 'app/main.py', 'app/page.tsx', 'src/main.tsx', 'main.go', 'src/main.rs']) if (ex(f) && !s.entry.includes(p(f))) s.entry.push(p(f));
+  if (!rel && ex('Makefile')) s.run.push(...nonEmpty(rd('Makefile')).filter((l) => /^[a-zA-Z][\w-]*:/.test(l)).slice(0, 6).map((l) => 'make ' + l.split(':')[0]));
+}
+
+function detect(root) {
+  const s = { langs: [], frameworks: [], tests: [], test: null, run: [], deps: [], entry: [] };
+  for (const rel of projectDirs(root)) detectIn(root, rel, s);
+  if (!s.frameworks.includes('Docker') && ['Dockerfile', 'docker-compose.yml', 'docker-compose.yaml', 'compose.yaml', 'compose.yml'].some((f) => fs.existsSync(path.join(root, f)))) s.frameworks.push('Docker');
+  // Fallback: languages with real source files but no manifest we recognise.
+  const files = names(tgit(['ls-files', '--cached', '--others', '--exclude-standard'], root));
+  const count = {};
+  for (const f of files) {
+    if (f.split('/').some((seg) => SKIP_DIRS.has(seg))) continue;
+    const l = EXT_LANG[f.split('.').pop().toLowerCase()];
+    if (l) count[l] = (count[l] || 0) + 1;
   }
-  if (ex('go.mod')) { s.langs.push('Go'); s.test = s.test || 'go test ./...'; }
-  if (ex('Cargo.toml')) { s.langs.push('Rust'); s.test = s.test || 'cargo test'; }
-  if (ex('Gemfile')) s.langs.push('Ruby');
-  if (ex('Dockerfile') || ex('docker-compose.yml') || ex('compose.yaml')) s.frameworks.push('Docker');
-  for (const f of ['main.py', 'app.py', 'server.js', 'index.js', 'src/server.js', 'src/server.ts', 'src/app.js', 'src/index.ts', 'src/main.ts', 'src/index.js', 'src/app.ts', 'app/page.tsx', 'src/main.tsx', 'main.go', 'src/main.rs']) if (ex(f) && !s.entry.includes(f)) s.entry.push(f);
-  if (ex('Makefile')) s.run.push(...nonEmpty(rd('Makefile')).filter((l) => /^[a-zA-Z][\w-]*:/.test(l)).slice(0, 6).map((l) => 'make ' + l.split(':')[0]));
+  for (const [l, n] of Object.entries(count)) if (n >= 3 && !s.langs.some((x) => x.split(' (')[0] === l)) s.langs.push(l);
+  s.deps = [...new Set(s.deps.filter(Boolean))];
+  s.test = s.tests.length ? s.tests.join(' && ') : null;
   return s;
 }
 
@@ -155,7 +201,7 @@ ${name} is ...
 
 ## Stack
 - ${stack}
-${st.test ? `- Tests: \`${st.test}\`\n` : ''}${st.run.length ? `- Run: ${st.run.map((x) => '`' + x + '`').join(', ')}\n` : ''}
+${st.tests.length ? `- Tests: ${st.tests.map((x) => '`' + x + '`').join(', ')}\n` : ''}${st.run.length ? `- Run: ${st.run.map((x) => '`' + x + '`').join(', ')}\n` : ''}
 ## Always
 - Read this charter, the current scope and the locked behaviours before changing code.
 - Make the smallest change that solves the task. Match the existing style and patterns.
@@ -187,7 +233,7 @@ function decisionsList(r) {
 function scopeBlock(r) {
   const s = r.scope;
   if (!s.task) return 'No scope is set. Before making broad changes, ask the human what the task is, or ask them to run `stet scope set`.';
-  return `**Task:** ${s.task}\n\nYou may change only:\n${s.allow.map((g) => `- \`${g}\``).join('\n')}\n\nIf the task needs a change outside this list, stop and ask. Do not tidy up, refactor or reformat other files.`;
+  return `${s.ticket ? `**Ticket:** ${s.ticket}\n` : ''}**Task:** ${s.task}\n\nYou may change only:\n${s.allow.map((g) => `- \`${g}\``).join('\n')}\n\nIf the task needs a change outside this list, stop and ask. Do not tidy up, refactor or reformat other files.`;
 }
 function locksBlock(r) {
   const L = r.locks;
@@ -253,7 +299,10 @@ function init(r, { name, mcp } = {}) {
   const put = (f, s) => { if (fs.existsSync(r.p(f))) kept.push(f); else { r.write(f, s); made.push(f); } };
   put('config.json', JSON.stringify({ name: nm, version: 1, protect: [], ignore: [], maxFileKB: 64, checkTimeoutSec: 600 }, null, 2) + '\n');
   put('charter.md', charterTemplate(nm, st));
-  put('locks.json', JSON.stringify(st.test ? [{ id: 'L1', name: 'Full test suite passes', cmd: st.test, protect: [], added: today() }] : [], null, 2) + '\n');
+  put('locks.json', JSON.stringify(st.tests.map((cmd, i) => {
+    const m = cmd.match(/^cd (\S+) && /);
+    return { id: 'L' + (i + 1), name: m ? `Test suite passes (${m[1]}/)` : 'Full test suite passes', cmd, protect: [], added: today() };
+  }), null, 2) + '\n');
   put('scope.json', '{}\n');
   put('decisions.md', `# Decision log — ${nm}\n\nOne entry per decision. Newest at the bottom. Managed with \`stet decide\`.\n\n## D-001 · ${today()} · Adopted Stet to keep AI agents in scope\nAI agents read AGENTS.md. Locked behaviours are checked with \`stet check\` before work is called done.\n`);
   put('.gitignore', '.cache/\ncontext.md\n');
@@ -353,18 +402,28 @@ function check(r, { only } = {}) {
 }
 
 // ---------- scope + guard ----------
-function scopeSet(r, task, { allow } = {}) {
+// Ticket IDs look like LIN-142, ENG-7, PROJ-1203 (Linear, Jira, Shortcut style).
+const TICKET_RE = /\b([A-Z][A-Z0-9]{1,9}-\d+)\b/;
+function scopeSet(r, task, { allow, ticket } = {}) {
   r.need();
   const a = splitList(allow);
-  if (!task || !a.length) throw new StetError('Usage: stet scope set "<task>" --allow "src/feature/**,tests/feature/**"');
-  r.wjson('scope.json', { task, allow: a, base: r.head(true) || null, set: new Date().toISOString() }); sync(r);
-  return out(`${OK()} Scope set: ${c.bold(task)}\n  allowed: ${a.map((g) => c.cyan(g)).join(', ')}\n  base:    ${r.head() || '(no commits)'} — guard compares everything changed since here`);
+  if (!task || !a.length) throw new StetError('Usage: stet scope set "<task>" --allow "src/feature/**,tests/feature/**" [--ticket LIN-142]');
+  // Ticket: explicit --ticket wins, otherwise taken from the task text ("LIN-142 Add CSV export").
+  let t = typeof ticket === 'string' ? ticket.trim().toUpperCase() : (task.match(TICKET_RE) || [])[1] || null;
+  if (t && !TICKET_RE.test(t)) throw new StetError(`"${ticket}" doesn't look like a ticket ID (expected something like LIN-142).`);
+  const cleanTask = t ? task.replace(new RegExp(`^\\s*${t}\\s*[:\\-–—]?\\s*`), '').trim() || task : task;
+  const decided = decisionsList(r);
+  r.wjson('scope.json', { ticket: t, task: cleanTask, allow: a, base: r.head(true) || null, set: new Date().toISOString(), decisionsBefore: decided.length });
+  sync(r);
+  return out(`${OK()} Scope set: ${t ? c.violet(t) + ' ' : ''}${c.bold(cleanTask)}\n  allowed: ${a.map((g) => c.cyan(g)).join(', ')}\n  base:    ${r.head() || '(no commits)'} — guard compares everything changed since here${t ? `\n  ticket:  ${t} is added to commit messages (stet hook install) and PR text (stet pr)` : ''}`);
 }
 function scopeShow(r) {
   r.need(); const s = r.scope;
   if (!s.task) return out('No scope set. Set one before an AI task: stet scope set "<task>" --allow "<globs>"');
-  return out(`${c.bold('Task:')} ${s.task}\n${c.bold('Allowed:')} ${s.allow.join(', ')}\n${c.dim(`Set ${s.set} at ${s.base ? s.base.slice(0, 7) : 'no commit'}`)}`);
+  return out(`${s.ticket ? `${c.bold('Ticket:')} ${s.ticket}\n` : ''}${c.bold('Task:')} ${s.task}\n${c.bold('Allowed:')} ${s.allow.join(', ')}\n${c.dim(`Set ${s.set} at ${s.base ? s.base.slice(0, 7) : 'no commit'}`)}`);
 }
+// Prints only the ticket ID (or nothing). Used by the prepare-commit-msg hook.
+function scopeTicket(r) { r.need(); return out(r.scope.ticket || ''); }
 function scopeClear(r) { r.need(); r.wjson('scope.json', {}); sync(r); return out(`${OK()} Scope cleared.`); }
 
 function guard(r, { base, staged, warn } = {}) {
@@ -380,7 +439,7 @@ function guard(r, { base, staged, warn } = {}) {
   }
   const lines = [];
   const what = staged ? 'staged files' : `changes since ${(base || s.base || 'HEAD').slice(0, 7)}`;
-  lines.push(c.bold(`Guarding ${files.length} changed file${files.length === 1 ? '' : 's'}`) + c.dim(` (${what})`) + (s.task ? c.dim(` · task: ${s.task}`) : ''));
+  lines.push(c.bold(`Guarding ${files.length} changed file${files.length === 1 ? '' : 's'}`) + c.dim(` (${what})`) + (s.task ? c.dim(` · ${s.ticket ? s.ticket + ' ' : 'task: '}${s.task}`) : ''));
   if (!s.task) lines.push(`${WARN()} No scope set, so only protected paths and locks are checked. Set one: stet scope set "<task>" --allow "<globs>"`);
   for (const f of files) {
     const bad = outScope.includes(f) || protectedHits.includes(f);
@@ -495,7 +554,7 @@ Generated by Stet ${VERSION} on ${today()}. Regenerate any time with \`stet hand
 ${charter}
 
 ## 2. Run it
-${st.run.length || st.test ? [...st.run, ...(st.test ? [st.test + '   # tests'] : [])].map((x) => '- `' + x + '`').join('\n') : '- No run scripts detected. Add them to the charter.'}
+${st.run.length || st.tests.length ? [...st.run, ...st.tests.map((t) => t + '   # tests')].map((x) => '- `' + x + '`').join('\n') : '- No run scripts detected. Add them to the charter.'}
 ${envKeys.length ? `\nEnvironment variables needed (names only, from the example env file):\n${envKeys.map((k) => '`' + k + '`').join(' · ')}` : ''}
 
 ## 3. Architecture at a glance
@@ -532,6 +591,96 @@ ${g ? `\nRecent commits:\n\`\`\`\n${r.tgit(['log', '--oneline', '--no-decorate',
   return out(md);
 }
 
+// ---------- PR / commit text ----------
+// Builds a commit message and PR description from facts only: the diff since the scope was set,
+// the scope and its ticket, guard results, the last stet check, and decisions logged during the task.
+// The one thing Stet can't know — the "why" in plain words — is left as a marked line for you or your AI.
+function pr(r, { base, runCheck } = {}) {
+  r.need();
+  if (!r.isGit() || !r.head()) throw new StetError('stet pr needs a git repo with at least one commit.');
+  const s = r.scope;
+  const want = base || s.base || 'HEAD';
+  const b = r.tgit(['rev-parse', '--verify', '--quiet', want + '^{commit}']).trim() ? want : 'HEAD';
+
+  // What changed (committed + staged + unstaged since base, plus new untracked files).
+  const status = {}, lines = {};
+  for (const l of nonEmpty(r.tgit(['diff', '--name-status', '-M', b]))) {
+    const [code, ...paths] = l.split('\t');
+    const f = paths[paths.length - 1];
+    status[f] = code[0] === 'A' ? 'added' : code[0] === 'D' ? 'deleted' : code[0] === 'R' ? `renamed from \`${paths[0]}\`` : 'modified';
+  }
+  for (const l of nonEmpty(r.tgit(['diff', '--numstat', '-M', b]))) {
+    const [add, del, ...rest] = l.split('\t');
+    // Renames show as "old => new" or "dir/{a => b}/file"; keep the new path.
+    const f = rest.join('\t').replace(/\{[^}]* => ([^}]*)\}/, '$1').replace(/^.* => /, '').replace(/\/\//g, '/');
+    lines[f] = add === '-' ? null : [+add, +del];
+  }
+  for (const f of names(r.tgit(['ls-files', '--others', '--exclude-standard']))) {
+    status[f] = 'added';
+    try { const t = fs.readFileSync(path.join(r.root, f)); lines[f] = t.includes(0) ? null : [t.toString('utf8').split('\n').length - (t.toString('utf8').endsWith('\n') ? 1 : 0), 0]; } catch { lines[f] = null; }
+  }
+  const files = Object.keys(status).filter((f) => !matches(f, STET_OWNED)).sort();
+  const plus = files.reduce((n, f) => n + ((lines[f] || [0])[0] || 0), 0);
+  const minus = files.reduce((n, f) => n + ((lines[f] || [0, 0])[1] || 0), 0);
+
+  // Scope and locks.
+  const g = guard(r, { base: b, warn: true }).data;
+  let checkRes = null, checkNote = '';
+  if (runCheck) { checkRes = check(r, {}).data.results; checkNote = `ran just now at commit \`${r.head()}\``; }
+  else {
+    const last = r.json('.cache/last-check.json', null);
+    if (last) {
+      checkRes = last.results;
+      checkNote = `last run ${last.at.slice(0, 16).replace('T', ' ')} UTC at commit \`${last.head}\`${last.head !== r.head() ? ' — older than the latest commit, rerun `stet check`' : ''}`;
+    }
+  }
+  const newDecisions = s.task ? decisionsList(r).slice(s.decisionsBefore || 0) : [];
+  const decMd = r.read('decisions.md');
+  const why = (id) => { const m = decMd.match(new RegExp(`^## ${id} · .*\\n([^#][\\s\\S]*?)(?=\\n## |$)`, 'm')); return m ? m[1].trim().split('\n')[0] : ''; };
+
+  const title = s.task ? `${s.ticket ? s.ticket + ': ' : ''}${s.task}` : 'Describe this change';
+  const MAX = 30;
+
+  // Commit message: title, blank line, one bullet per file.
+  const commit = [title, '', ...files.slice(0, 15).map((f) => `- ${status[f].startsWith('renamed') ? 'rename' : status[f] === 'added' ? 'add' : status[f] === 'deleted' ? 'remove' : 'update'} ${f}`), ...(files.length > 15 ? [`- and ${files.length - 15} more files`] : [])].join('\n') + '\n';
+
+  const md = [];
+  md.push(`## ${title}`, '');
+  if (s.ticket) md.push(`**Ticket:** ${s.ticket}`, '');
+  md.push('### What and why', '<!-- Replace this line with 1–2 sentences: what changes for the user, and why. -->', s.task ? `${s.task}.` : '', '');
+  md.push(`### Changes · ${files.length} file${files.length === 1 ? '' : 's'}, +${plus} −${minus}`);
+  if (files.length) {
+    md.push('| File | Change | Lines |', '|---|---|---|');
+    for (const f of files.slice(0, MAX)) md.push(`| \`${f}\` | ${status[f]} | ${lines[f] ? `+${lines[f][0]} −${lines[f][1]}` : 'binary'} |`);
+    if (files.length > MAX) md.push(`| … | ${files.length - MAX} more files | |`);
+  } else md.push('No changes since the base commit yet.');
+  md.push('');
+  md.push('### Scope');
+  if (!s.task) md.push('⚠️ No scope was set for this change.');
+  else if (g.violations.length) md.push(`⚠️ ${g.violations.length} file${g.violations.length > 1 ? 's are' : ' is'} outside the agreed scope or in protected paths:`, ...g.violations.map((f) => `- \`${f}\``), `Agreed scope: ${s.allow.map((x) => '`' + x + '`').join(', ')}`);
+  else md.push(`✅ All changes are inside the agreed scope: ${s.allow.map((x) => '`' + x + '`').join(', ')}`);
+  md.push('');
+  md.push('### Locked behaviours');
+  if (!checkRes || !checkRes.length) md.push(r.locks.length ? '⚠️ `stet check` has not been run for this change yet.' : 'No locked behaviours in this repo yet.');
+  else {
+    for (const x of checkRes) md.push(`- ${x.ok ? '✅' : x.cantRun ? '⚠️' : '❌'} **${x.id}** ${x.name}${x.ok ? '' : x.cantRun ? ' — proof command could not run' : ' — failing'}`);
+    md.push('', `<sub>stet check ${checkNote}</sub>`);
+  }
+  if (g.lockIds.length) md.push('', `Touches files watched by ${g.lockIds.join(', ')}.`);
+  md.push('');
+  if (newDecisions.length) {
+    md.push('### Decisions made in this change');
+    for (const d of newDecisions) { const w = why(d.id); md.push(`- **${d.id}** ${d.title}${w ? ` — ${w}` : ''}`); }
+    md.push('');
+  }
+  md.push('---', '<sub>Generated by [Stet](https://github.com/shamazkhan/stet) from the git diff, the task scope and check results.</sub>', '');
+
+  const prText = md.join('\n');
+  r.write('.cache/pr.md', prText);
+  r.write('.cache/commit.txt', commit);
+  return out(prText, 0, { title, commit, pr: prText, files: files.length, violations: g.violations, checks: checkRes });
+}
+
 // ---------- status ----------
 function status(r) {
   r.need();
@@ -548,24 +697,41 @@ function status(r) {
 }
 
 // ---------- git hook ----------
+const HOOK_BEG = '# >>> stet >>>', HOOK_END = '# <<< stet <<<';
+const STET_BIN = 'if command -v stet >/dev/null 2>&1; then STET="stet"; else STET="npx --no-install stet-cli"; fi';
+function writeHook(hp, block) {
+  let cur = fs.existsSync(hp) ? fs.readFileSync(hp, 'utf8') : '';
+  if (cur.includes(HOOK_BEG)) cur = cur.slice(0, cur.indexOf(HOOK_BEG)) + cur.slice(cur.indexOf(HOOK_END) + HOOK_END.length + 1);
+  if (block == null) { if (fs.existsSync(hp)) fs.writeFileSync(hp, cur); return; }
+  const next = (cur.trim() ? cur.replace(/\s*$/, '\n') : '#!/bin/sh\n') + block;
+  fs.mkdirSync(path.dirname(hp), { recursive: true });
+  fs.writeFileSync(hp, next); fs.chmodSync(hp, 0o755);
+}
 function hook(r, { uninstall, withCheck } = {}) {
   r.need();
   const gitDir = r.tgit(['rev-parse', '--git-path', 'hooks']).trim();
   if (!gitDir) throw new StetError('Not a git repo.');
-  const hp = path.resolve(r.root, gitDir, 'pre-commit');
-  const BEG = '# >>> stet >>>', FIN = '# <<< stet <<<';
-  let cur = fs.existsSync(hp) ? fs.readFileSync(hp, 'utf8') : '';
-  if (cur.includes(BEG)) cur = cur.slice(0, cur.indexOf(BEG)) + cur.slice(cur.indexOf(FIN) + FIN.length + 1);
-  if (uninstall) { fs.writeFileSync(hp, cur); return out(`${OK()} Removed Stet from the pre-commit hook.`); }
-  const block = `${BEG}
-if command -v stet >/dev/null 2>&1; then STET="stet"; else STET="npx --no-install stet"; fi
+  const pre = path.resolve(r.root, gitDir, 'pre-commit');
+  const msg = path.resolve(r.root, gitDir, 'prepare-commit-msg');
+  if (uninstall) { writeHook(pre, null); writeHook(msg, null); return out(`${OK()} Removed Stet from the git hooks.`); }
+  // pre-commit: block commits that stage out-of-scope or protected files.
+  writeHook(pre, `${HOOK_BEG}
+${STET_BIN}
 $STET guard --staged || { echo "stet: commit blocked. Out-of-scope or protected files are staged. Bypass on purpose with: git commit --no-verify"; exit 1; }
-${withCheck ? '$STET check || { echo "stet: commit blocked. A locked behaviour is failing."; exit 1; }\n' : 'if [ "$STET_CHECK" = "1" ]; then $STET check || exit 1; fi\n'}${FIN}
-`;
-  const next = (cur.trim() ? cur.replace(/\s*$/, '\n') : '#!/bin/sh\n') + block;
-  fs.mkdirSync(path.dirname(hp), { recursive: true });
-  fs.writeFileSync(hp, next); fs.chmodSync(hp, 0o755);
-  return out(`${OK()} Pre-commit hook installed: blocks commits that stage out-of-scope or protected files${withCheck ? ' and runs stet check' : ' (set STET_CHECK=1 to also run stet check)'}.`);
+${withCheck ? '$STET check || { echo "stet: commit blocked. A locked behaviour is failing."; exit 1; }\n' : 'if [ "$STET_CHECK" = "1" ]; then $STET check || exit 1; fi\n'}${HOOK_END}
+`);
+  // prepare-commit-msg: prefix the ticket ID ("LIN-142: ...") unless the message already has it.
+  // $2 is empty (editor) or "message" (-m); merges, squashes and amends are left alone.
+  writeHook(msg, `${HOOK_BEG}
+case "$2" in ""|message|template)
+  ${STET_BIN}
+  T=$($STET scope ticket --no-color 2>/dev/null)
+  if [ -n "$T" ] && ! grep -q "$T" "$1"; then { printf '%s: ' "$T"; cat "$1"; } > "$1.stet" && mv "$1.stet" "$1"; fi
+  ;;
+esac
+${HOOK_END}
+`);
+  return out(`${OK()} Git hooks installed:\n  pre-commit          blocks commits that stage out-of-scope or protected files${withCheck ? ' and runs stet check' : ' (STET_CHECK=1 also runs stet check)'}\n  prepare-commit-msg  adds the scope's ticket ID to commit messages, e.g. "LIN-142: …"`);
 }
 
 // ---------- MCP config ----------
@@ -577,4 +743,4 @@ function mcpInstall(r) {
   return out(`${OK()} Wrote .mcp.json. Claude Code picks up the Stet tools in this project.\n  Cursor: add the same "stet" entry to .cursor/mcp.json.\n  Anywhere else: command \`npx -y stet-cli mcp\` (stdio).`);
 }
 
-module.exports = { VERSION, Repo, StetError, findRoot, setColor, c, init, sync, decide, decisions, lockAdd, lockList, lockRm, check, scopeSet, scopeShow, scopeClear, guard, context, copyToClipboard, handoff, status, hook, mcpInstall, globRe, matches, detect, listFiles, changedFiles };
+module.exports = { VERSION, Repo, StetError, findRoot, setColor, c, init, sync, decide, decisions, lockAdd, lockList, lockRm, check, scopeSet, scopeShow, scopeClear, guard, context, copyToClipboard, handoff, status, hook, mcpInstall, pr, scopeTicket, globRe, matches, detect, listFiles, changedFiles };

package/lib/mcp.js

@@ -8,6 +8,8 @@ const TOOLS = [
   { name: 'stet_guard', description: 'Check that every file changed so far is inside the agreed task scope and outside protected paths. Run after making changes and before reporting a task as done.', inputSchema: { type: 'object', properties: {} } },
   { name: 'stet_check', description: 'Run the locked behaviours (the commands that prove existing features still work). Run before reporting a task as done. If one fails, fix your change; never edit the test or weaken the check.', inputSchema: { type: 'object', properties: { only: { type: 'array', items: { type: 'string' }, description: 'Lock IDs to run, e.g. ["L2"]. Default: all.' } } } },
   { name: 'stet_scope', description: 'Read the current task scope: the task and the file globs you may change. Only the human can change the scope.', inputSchema: { type: 'object', properties: {} } },
+  { name: 'stet_pr', description: 'Draft the commit message and pull request description for the current task from facts: the git diff since the scope was set, the ticket ID, scope results, the last stet check and decisions logged. Fill in the "What and why" line yourself. Use runCheck to run the locked behaviours first.',
+    inputSchema: { type: 'object', properties: { base: { type: 'string', description: 'Branch or commit to compare against, e.g. "main". Default: where the scope was set.' }, runCheck: { type: 'boolean', description: 'Run stet check first' } } } },
   { name: 'stet_decide', description: 'Record an architectural or product decision in the decision log so future sessions and teammates do not reopen it.', inputSchema: { type: 'object', properties: { decision: { type: 'string' }, why: { type: 'string' } }, required: ['decision'] } },
 ];
 
@@ -18,6 +20,7 @@ function callTool(name, a = {}) {
     case 'stet_guard': return core.guard(r, {});
     case 'stet_check': return core.check(r, { only: a.only });
     case 'stet_scope': return core.scopeShow(r);
+    case 'stet_pr': { const p = core.pr(r, { base: a.base, runCheck: a.runCheck }); return { text: `COMMIT MESSAGE\n\n${p.data.commit}\nPR DESCRIPTION\n\n${p.data.pr}`, code: 0 }; }
     case 'stet_decide': return core.decide(r, a.decision, { why: a.why });
     default: throw new core.StetError('Unknown tool: ' + name);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stet-cli",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Keep AI coding agents from breaking what already works. Charter, locked behaviours, scope guard, decision log and git-synced context for Claude Code, Cursor, Codex and any chat.",
   "bin": {
     "stet": "bin/stet.js"