stet-cli 0.1.3 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.3.0 — 2026-11-14
+- Linear integration (optional, needs `LINEAR_API_KEY`): `stet ticket LIN-142` fetches a ticket; `stet scope set LIN-142 --allow …` uses the Linear title as the task.
+- The ticket (title, status, priority, labels, link, description) is included at the top of `stet context`, so one paste gives your AI the ticket and the code.
+- `stet pr` links the ticket ID to Linear.
+- Privacy: only the ticket ID is sent to Linear; tickets are cached in `.stet/.cache/` (gitignored).
+
+## 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`).

package/README.md

@@ -9,10 +9,13 @@ 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.
+- **Linear tickets.** `stet scope set LIN-142 --allow "…"` pulls the ticket's title and description from Linear into the context pack, so your AI gets the ticket and the code in one paste.
+- **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.
 
 No account. No telemetry. Your code never leaves your machine. Zero dependencies. Node 18+.
+The only network call is optional: if you set `LINEAR_API_KEY`, `stet ticket` fetches the Linear ticket you name (only the ticket ID is sent).
 
 ## Install
 
@@ -43,13 +46,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 +88,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,13 +97,35 @@ 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 ticket [LIN-142] [--stdout] [--cached]` | Fetch a Linear ticket (needs `LINEAR_API_KEY`). It is included in `stet context` and linked in `stet pr`. With no ID, shows the current scope's ticket. |
+| `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`. |
 
 Add `--json` to any command for machine-readable output.
 
+## Linear
+
+1. In Linear: **Settings → Security & access → Personal API keys → New key** (read access is enough).
+2. Put it in your shell, never in the repo:
+
+```bash
+echo 'export LINEAR_API_KEY=lin_api_...' >> ~/.zshrc && source ~/.zshrc
+```
+
+3. Work from tickets:
+
+```bash
+stet scope set LIN-142 --allow "src/export/**,tests/export/**"   # task = the Linear title
+stet context --files "src/export/**"   # ticket + rules + code, ready to paste into ChatGPT
+stet ticket                            # show the current ticket again (stet ticket LIN-150 for another)
+stet pr                                # PR text links back to the Linear ticket
+```
+
+Tickets are cached in `.stet/.cache/` (gitignored). Only the ticket ID is sent to Linear; nothing about your code is.
+
 ## Use with your AI tools
 
 **Claude Code:** run `stet init --mcp`, or `claude mcp add stet -- npx -y stet-cli mcp`. Claude Code reads `CLAUDE.md`, which imports `AGENTS.md`.
@@ -111,7 +140,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
 
@@ -138,7 +167,7 @@ Globs support `*`, `**` and `?`. A bare folder name like `migrations` matches ev
 
 ## FAQ
 
-**Does Stet send my code anywhere?** No. It's a local CLI with no network calls and no telemetry.
+**Does Stet send my code anywhere?** No. It's a local CLI with no telemetry. Its only network call is the optional Linear fetch, which sends just the ticket ID you ask for.
 
 **Is this just AGENTS.md?** `AGENTS.md` tells the agent the rules. Stet keeps those rules current, and `guard` and `check` verify the agent actually followed them.
 

package/bin/stet.js

@@ -5,7 +5,7 @@ const path = require('path');
 const core = require('../lib/core');
 const { c } = core;
 
-const BOOL = new Set(['help', 'h', 'version', 'v', 'staged', 'warn', 'diff', 'changed', 'stdout', 'copy', 'all', 'mcp', 'uninstall', 'check', 'json', 'no-color']);
+const BOOL = new Set(['help', 'h', 'version', 'v', 'staged', 'warn', 'diff', 'changed', 'stdout', 'copy', 'all', 'mcp', 'uninstall', 'check', 'json', 'no-color', 'cached']);
 function parse(argv) {
   const pos = [], fl = {};
   for (let i = 0; i < argv.length; i++) {
@@ -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,15 @@ ${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('Linear')}  (optional · needs LINEAR_API_KEY in your shell)
+  stet ticket LIN-142 [--stdout|--json]   Fetch a ticket; it goes into stet context and stet pr
+  stet scope set LIN-142 --allow "<globs>"  Uses the Linear title as the task
+
+${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]
@@ -52,7 +62,7 @@ ${c.bold('Team')}
 
 Docs: https://stet-8fe08a58.base44.app`;
 
-function main() {
+async function main() {
   const { pos, fl } = parse(process.argv.slice(2));
   if (fl['no-color']) core.setColor(false);
   const [cmd, sub, ...rest] = pos;
@@ -77,9 +87,26 @@ 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') {
+        let task = rest.join(' ');
+        const id = (typeof fl.ticket === 'string' ? fl.ticket : (task.match(/\b[A-Z][A-Z0-9]{1,9}-\d+\b/) || [])[0] || '').toUpperCase();
+        const notes = [];
+        // With LINEAR_API_KEY set, fetch the ticket so its title and description reach the context pack.
+        if (id && process.env.LINEAR_API_KEY) {
+          try {
+            const linear = require('../lib/linear');
+            const issue = await linear.fetchIssue(id);
+            linear.saveIssue(r, issue);
+            if (task.trim().toUpperCase() === id) task = `${id} ${issue.title}`; // "stet scope set LIN-142" → use the Linear title
+            notes.push(`${c.green('✓')} Linear: ${issue.title}${issue.state ? c.dim(' · ' + issue.state.name) : ''}`);
+          } catch (e) { notes.push(c.yellow(`! Linear: ${e.message.split('\n')[0]} (scope set anyway)`)); }
+        }
+        res = core.scopeSet(r, task, { allow: fl.allow, ticket: fl.ticket });
+        if (notes.length) res.text += '\n' + notes.map((n) => '  ' + n).join('\n');
+      }
+      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 +129,44 @@ 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 'ticket': {
+      const linear = require('../lib/linear');
+      r.need();
+      const id = (sub || r.scope.ticket || '').toUpperCase();
+      if (!id) throw new core.StetError('Usage: stet ticket LIN-142   (or set a scope with a ticket ID first)');
+      let issue = fl.cached ? linear.cachedIssue(r, id) : null;
+      if (!issue) { issue = await linear.fetchIssue(id); linear.saveIssue(r, issue); }
+      if (fl.stdout) { process.stdout.write(linear.issueMd(issue) + '\n'); return; }
+      const body = linear.issueMd(issue).split('\n');
+      res = { code: 0, text: [
+        `${c.green('✓')} ${c.violet(issue.identifier)} ${c.bold(issue.title)}`,
+        ...body.slice(1, 3).filter(Boolean).map((l) => '  ' + c.dim(l)),
+        '', ...body.slice(3).join('\n').trim().split('\n').slice(0, 12).map((l) => '  ' + l),
+      ].join('\n'), data: issue };
+      res.text += '\n' + [
+        '', c.dim(`  Saved for this repo. ${r.scope.ticket === issue.identifier ? 'It is included in stet context and stet pr.' : `Start work on it: stet scope set ${issue.identifier} --allow "<globs>"`}`),
+      ].join('\n');
+      break;
+    }
     case 'status': case 'st': res = core.status(r); break;
     case 'hook':
       if (sub === 'install') res = core.hook(r, { withCheck: fl.check });
@@ -118,7 +183,7 @@ function main() {
   process.exitCode = res.code;
 }
 
-try { main(); } catch (e) {
+main().catch((e) => {
   if (e instanceof core.StetError) { console.error(c.red('stet: ') + e.message); process.exitCode = e.code || 1; }
   else { console.error(e); process.exitCode = 2; }
-}
+});

package/lib/core.js

@@ -233,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;
@@ -402,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 } = {}) {
@@ -429,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);
@@ -481,6 +491,9 @@ function context(r, { files, changed, diff, maxKB } = {}) {
   parts.push(`# Context pack — ${cfg.name}`);
   parts.push(`Generated by Stet ${VERSION} on ${new Date().toISOString().replace('T', ' ').slice(0, 16)} UTC · branch \`${g ? r.branch() : 'n/a'}\` · commit \`${g ? r.head() || 'none' : 'n/a'}\` · ${status.length} uncommitted change${status.length === 1 ? '' : 's'} · ${all.length} files`);
   parts.push(`> **For the AI reading this:** this is the live state of the repository right now. It replaces any code, file list or assumption from earlier in this conversation. Follow the working agreement below. Do not invent files that are not in the tree. If you need a file's contents, ask for it by path.`);
+  // The Linear ticket (if fetched with `stet ticket` / `stet scope set LIN-142`) goes first: it is the task.
+  const tk = r.scope.ticket && require('./linear').cachedIssue(r, r.scope.ticket);
+  if (tk) parts.push(require('./linear').issueMd(tk));
   parts.push(agentsBlock(r).replace(BEGIN, '').replace(END, '').replace(/^<!--.*-->$/m, '').replace(/^### /gm, '#### ').replace(/^# Working agreement.*$/m, '## Working agreement').replace(/^## (?!Working)/gm, '### ').trim());
   if (g && r.head()) parts.push(`## Recent commits\n\`\`\`\n${r.tgit(['log', '--oneline', '--no-decorate', '-15']).trim()}\n\`\`\``);
   if (status.length) parts.push(`## Uncommitted changes\n\`\`\`\n${status.join('\n')}\n\`\`\``);
@@ -581,6 +594,97 @@ ${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}`, '');
+  const tk = s.ticket && require('./linear').cachedIssue(r, s.ticket);
+  if (s.ticket) md.push(`**Ticket:** ${tk && tk.url ? `[${s.ticket}](${tk.url})` : 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();
@@ -597,24 +701,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 ----------
@@ -626,4 +747,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/linear.js

@@ -0,0 +1,86 @@
+'use strict';
+// Optional Linear integration.
+// The only network call Stet makes: when you ask for a ticket and LINEAR_API_KEY is set,
+// it fetches that one issue from Linear. Nothing about your code is ever sent.
+const fs = require('fs');
+const path = require('path');
+const { StetError } = require('./core');
+
+const LINEAR_URL = process.env.STET_LINEAR_URL || 'https://api.linear.app/graphql';
+const ID_RE = /^[A-Z][A-Z0-9]{1,9}-\d+$/;
+
+const QUERY = `query StetIssue($id: String!) {
+  issue(id: $id) {
+    identifier title description url priorityLabel
+    state { name } assignee { name } project { name }
+    labels { nodes { name } }
+  }
+}`;
+
+function apiKey() {
+  const k = (process.env.LINEAR_API_KEY || '').trim();
+  if (!k) {
+    throw new StetError(
+      'LINEAR_API_KEY is not set.\n' +
+      '  1. In Linear: Settings → Security & access → Personal API keys → New key (read access is enough)\n' +
+      '  2. Add it to your shell, not to the repo:  echo \'export LINEAR_API_KEY=lin_api_...\' >> ~/.zshrc && source ~/.zshrc'
+    );
+  }
+  return k;
+}
+
+// Personal API keys go in the header as-is; OAuth tokens need "Bearer".
+const authHeader = (k) => (k.startsWith('lin_oauth') ? `Bearer ${k}` : k);
+
+async function fetchIssue(id) {
+  id = String(id || '').trim().toUpperCase();
+  if (!ID_RE.test(id)) throw new StetError(`"${id}" doesn't look like a Linear ticket ID (expected something like LIN-142).`);
+  const key = apiKey();
+  let res;
+  try {
+    res = await fetch(LINEAR_URL, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Authorization: authHeader(key) },
+      body: JSON.stringify({ query: QUERY, variables: { id } }),
+    });
+  } catch (e) {
+    throw new StetError(`Couldn't reach Linear (${e.cause?.code || e.message}). Check your internet connection.`);
+  }
+  if (res.status === 401 || res.status === 403) throw new StetError('Linear rejected the API key. Check LINEAR_API_KEY (Settings → Security & access → Personal API keys).');
+  let body;
+  try { body = await res.json(); } catch { throw new StetError(`Linear returned an unexpected response (HTTP ${res.status}).`); }
+  const issue = body && body.data && body.data.issue;
+  if (!issue) {
+    const msg = (body && body.errors && body.errors[0] && body.errors[0].message) || 'not found';
+    throw new StetError(`Linear ticket ${id}: ${msg}. Check the ID and that your key's workspace can see it.`);
+  }
+  return issue;
+}
+
+// Cache lives in .stet/.cache (gitignored), so ticket text never ends up in the repo.
+const cachePath = (r, id) => r.p('.cache', 'tickets', `${id}.json`);
+function saveIssue(r, issue) {
+  const f = cachePath(r, issue.identifier);
+  fs.mkdirSync(path.dirname(f), { recursive: true });
+  fs.writeFileSync(f, JSON.stringify({ ...issue, fetchedAt: new Date().toISOString() }, null, 2) + '\n');
+}
+function cachedIssue(r, id) {
+  if (!id) return null;
+  try { return JSON.parse(fs.readFileSync(cachePath(r, id), 'utf8')); } catch { return null; }
+}
+
+// Markdown block used in the context pack and `stet ticket` output.
+function issueMd(issue, { maxChars = 8000 } = {}) {
+  const meta = [
+    issue.state && issue.state.name && `Status: ${issue.state.name}`,
+    issue.priorityLabel && issue.priorityLabel !== 'No priority' && `Priority: ${issue.priorityLabel}`,
+    issue.assignee && issue.assignee.name && `Assignee: ${issue.assignee.name}`,
+    issue.project && issue.project.name && `Project: ${issue.project.name}`,
+    issue.labels && issue.labels.nodes && issue.labels.nodes.length && `Labels: ${issue.labels.nodes.map((l) => l.name).join(', ')}`,
+  ].filter(Boolean).join(' · ');
+  let desc = (issue.description || '').trim() || '_No description in Linear._';
+  if (desc.length > maxChars) desc = desc.slice(0, maxChars) + '\n\n… (ticket description truncated)';
+  return `## Ticket ${issue.identifier}: ${issue.title}\n${meta ? meta + '\n' : ''}${issue.url ? `Link: ${issue.url}\n` : ''}\n${desc}`;
+}
+
+module.exports = { fetchIssue, saveIssue, cachedIssue, issueMd, ID_RE };

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.3",
+  "version": "0.3.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"