stet-cli 0.0.0-stage → 0.1.2

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.2 — 2026-11-13
+- Published on npm as stet-cli (the command is still `stet`).
+
+## 0.1.1 — 2026-11-13
+- stet check now says when a proof command cannot run (missing script, command not found) instead of reporting a regression.
+
+## 0.1.0 — 2026-11-13
+First release: init, sync, scope, guard, lock, check, context, decide, handoff, hook, status, mcp.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shamaz Khan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,149 @@
-# Temporary Holding Version
+# stet
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Stop AI coding agents from breaking what already works.**
+
+Stet is a small, free command-line tool that gives every AI coding tool (Claude Code, Cursor, Codex, Copilot, Windsurf or a plain chat) the same rules, the same up-to-date picture of your repo, and a hard check before work is called done.
+
+- **Charter → `AGENTS.md`.** Write your product context and do's and don'ts once in `.stet/charter.md`. Stet keeps `AGENTS.md` (read by Codex, Cursor, Copilot and others) and `CLAUDE.md` in sync.
+- **Locked behaviours.** Lock what already works, each with a command that proves it. `stet check` runs them all. If one fails, the AI fixes its change, not the test.
+- **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.
+- **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+.
+
+## Install
+
+```bash
+npm install -g stet-cli        # or run any command with: npx stet-cli <command>
+cd your-project
+stet init
+```
+
+`stet init` detects your stack and test command, then creates:
+
+```
+.stet/
+  charter.md      what this is, stack, always / never rules   ← edit this
+  config.json     name, protected paths, ignore globs
+  locks.json      locked behaviours
+  scope.json      current task scope
+  decisions.md    decision log
+AGENTS.md         generated working agreement (your own text outside the stet block is kept)
+CLAUDE.md         imports AGENTS.md for Claude Code
+```
+
+Commit `.stet/`, `AGENTS.md` and `CLAUDE.md`. Every agent and teammate then works from the same rules.
+
+## The loop
+
+```bash
+# 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*"
+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?
+```
+
+Example (real output from a sample accounting app):
+
+```
+$ stet guard
+Guarding 4 changed files (changes since 12b672b) · task: Add CSV export of invoices
+  ✗ migrations/002_export.sql  out of scope  protected
+  ✓ src/export/csv.js
+  ✗ src/vat/vat.js  out of scope  affects L2
+  ✓ test/export.test.js
+
+✗ 2 files outside scope or protected. Revert, or widen the scope on purpose.
+! Changes touch locked behaviour L2. Run: stet check --only L2
+
+$ stet check
+Checking 2 locked behaviours
+✗ L2   UAE VAT maths is correct (0.1s)
+     │ not ok 1 - 5% standard VAT, rounded to fils
+     │ expected: 10
+     │ actual: 9.99
+
+✗ 1 locked behaviour broken: L2. Fix the change, not the check.
+```
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `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 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. |
+| `stet check [--only L1,L2]` | Run locked behaviours. Exits 1 if any fail and shows the failing lines. |
+| `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 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 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.
+
+## 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`.
+
+**Cursor:** add this to `.cursor/mcp.json`:
+
+```json
+{ "mcpServers": { "stet": { "command": "npx", "args": ["-y", "stet-cli", "mcp"] } } }
+```
+
+**Codex, Copilot, Windsurf, Gemini CLI:** they read `AGENTS.md` directly.
+
+**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`.
+
+## Configuration
+
+`.stet/config.json`:
+
+```json
+{
+  "name": "Ledgerly",
+  "protect": ["migrations/**", ".github/**"],
+  "ignore": ["fixtures/**"],
+  "maxFileKB": 64,
+  "checkTimeoutSec": 600
+}
+```
+
+Globs support `*`, `**` and `?`. A bare folder name like `migrations` matches everything inside it.
+
+## In CI
+
+```yaml
+- run: npx -y stet-cli guard --base origin/main --warn
+- run: npx -y stet-cli check
+```
+
+## FAQ
+
+**Does Stet send my code anywhere?** No. It's a local CLI with no network calls and no telemetry.
+
+**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.
+
+**What if a locked behaviour has to change on purpose?** Change it deliberately: update the test, then `stet lock rm` / `stet lock add`, and record why with `stet decide`.
+
+## Licence
+
+MIT

package/bin/stet.js

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+'use strict';
+const fs = require('fs');
+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']);
+function parse(argv) {
+  const pos = [], fl = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--') || (a.startsWith('-') && a.length === 2)) {
+      let k = a.replace(/^--?/, ''), v;
+      if (k.includes('=')) [k, v] = [k.slice(0, k.indexOf('=')), k.slice(k.indexOf('=') + 1)];
+      else if (BOOL.has(k)) v = true;
+      else v = argv[i + 1] !== undefined && !argv[i + 1].startsWith('--') ? argv[++i] : true;
+      fl[k] = v;
+    } else pos.push(a);
+  }
+  return { pos, fl };
+}
+
+const HELP = `${c.bold('stet')} ${c.dim(core.VERSION)} — keep AI coding agents from breaking what already works
+
+${c.bold('Setup')}
+  stet init [--name X] [--mcp]        Create .stet/, AGENTS.md and CLAUDE.md (detects your stack)
+  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 context [--files "glob,glob"] [--changed] [--diff] [--copy|--stdout|--out file]
+                                      Git-synced context pack for any AI chat (no more uploading src/)
+
+${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('Memory')}
+  stet lock add "<behaviour>" --cmd "<proof command>" [--protect "glob,glob"]
+  stet lock [list|rm L2]
+  stet decide "<decision>" [--why "<reason>"]   Append to the decision log
+  stet decisions [--all]
+
+${c.bold('Team')}
+  stet handoff [--out HANDOFF.md]     Onboarding pack for a new dev or CTO, built from the repo
+  stet hook install [--check] | stet hook uninstall
+  stet status
+  stet mcp                            Run as an MCP server (Claude Code, Cursor, any MCP client)
+  stet mcp install                    Write .mcp.json for this project
+
+Docs: https://stet-8fe08a58.base44.app`;
+
+function main() {
+  const { pos, fl } = parse(process.argv.slice(2));
+  if (fl['no-color']) core.setColor(false);
+  const [cmd, sub, ...rest] = pos;
+  if (fl.version || fl.v) return console.log(core.VERSION);
+  if (!cmd || cmd === 'help' || fl.help || fl.h) return console.log(HELP);
+  if (cmd === 'mcp' && !sub) return require('../lib/mcp').serve();
+
+  const root = core.findRoot(process.cwd());
+  const r = new core.Repo(root);
+  let res;
+  switch (cmd) {
+    case 'init': res = core.init(r, { name: fl.name, mcp: fl.mcp }); break;
+    case 'sync': res = core.sync(r); break;
+    case 'decide': res = core.decide(r, [sub, ...rest].filter(Boolean).join(' '), { why: fl.why }); break;
+    case 'decisions': res = core.decisions(r, { all: fl.all }); break;
+    case 'lock': case 'locks':
+      if (!sub || sub === 'list' || sub === 'ls') res = core.lockList(r);
+      else if (sub === 'add') res = core.lockAdd(r, rest.join(' '), { cmd: fl.cmd, protect: fl.protect });
+      else if (sub === 'rm' || sub === 'remove') res = core.lockRm(r, rest[0]);
+      else throw new core.StetError('Usage: stet lock [list|add|rm]');
+      break;
+    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 === 'clear') res = core.scopeClear(r);
+      else throw new core.StetError('Usage: stet scope [show|set|clear]');
+      break;
+    case 'guard': res = core.guard(r, { staged: fl.staged, base: fl.base, warn: fl.warn }); break;
+    case 'context': case 'ctx': {
+      core.setColor(false);
+      const ctx = core.context(r, { files: fl.files, changed: fl.changed, diff: fl.diff, maxKB: fl['max-kb'] });
+      core.setColor((process.stdout.isTTY || process.env.STET_COLOR === '1') && !process.env.NO_COLOR && !fl['no-color']);
+      if (fl.stdout) { process.stdout.write(ctx.text); return; }
+      const file = fl.out ? path.resolve(fl.out) : r.p('context.md');
+      fs.writeFileSync(file, ctx.text);
+      const copied = fl.copy || !fl.out ? core.copyToClipboard(ctx.text) : false;
+      const kb = (Buffer.byteLength(ctx.text) / 1024).toFixed(1);
+      res = { code: 0, text: `${c.green('✓')} Context pack: ${c.bold(path.relative(process.cwd(), file) || file)} ${c.dim(`(${kb} KB, ~${Math.round(Buffer.byteLength(ctx.text) / 4).toLocaleString()} tokens, ${ctx.data.files} files in tree, ${ctx.data.included} with contents)`)}\n  ${copied ? 'Copied to clipboard. Paste it at the top of your AI chat.' : 'Attach or paste this file at the top of your AI chat.'}` };
+      break;
+    }
+    case 'handoff': {
+      const h = core.handoff(r);
+      if (fl.stdout) { process.stdout.write(h.text); return; }
+      const file = path.resolve(fl.out || path.join(root, 'HANDOFF.md'));
+      fs.writeFileSync(file, h.text);
+      res = { code: 0, text: `${c.green('✓')} Handoff pack written to ${c.bold(path.relative(process.cwd(), file) || file)}` };
+      break;
+    }
+    case 'status': case 'st': res = core.status(r); break;
+    case 'hook':
+      if (sub === 'install') res = core.hook(r, { withCheck: fl.check });
+      else if (sub === 'uninstall') res = core.hook(r, { uninstall: true });
+      else throw new core.StetError('Usage: stet hook install [--check] | stet hook uninstall');
+      break;
+    case 'mcp':
+      if (sub === 'install') res = core.mcpInstall(r); else throw new core.StetError('Usage: stet mcp | stet mcp install');
+      break;
+    default: throw new core.StetError(`Unknown command "${cmd}". Run stet help.`);
+  }
+  if (fl.json) console.log(JSON.stringify({ code: res.code, data: res.data, text: res.text.replace(/\x1b\[[0-9;]*m/g, '') }, null, 2));
+  else console.log(res.text);
+  process.exitCode = res.code;
+}
+
+try { 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

@@ -0,0 +1,580 @@
+'use strict';
+// Stet core: every command returns { text, code } so the CLI and the MCP server share one implementation.
+const fs = require('fs');
+const path = require('path');
+const cp = require('child_process');
+const VERSION = require('../package.json').version;
+
+// ---------- output helpers ----------
+let COLOR = (!!process.stdout.isTTY || process.env.STET_COLOR === '1') && !process.env.NO_COLOR;
+const setColor = (v) => { COLOR = !!v; };
+const paint = (code) => (s) => (COLOR ? `\x1b[${code}m${s}\x1b[0m` : String(s));
+const c = { bold: paint(1), dim: paint(2), red: paint(31), green: paint(32), yellow: paint(33), cyan: paint(36), violet: paint(35) };
+const OK = () => c.green('✓'), BAD = () => c.red('✗'), WARN = () => c.yellow('!');
+const today = () => new Date().toISOString().slice(0, 10);
+const out = (text, code = 0, data) => ({ text, code, data });
+
+class StetError extends Error { constructor(m, code = 1) { super(m); this.code = code; } }
+
+// ---------- git + fs ----------
+function sh(cmd, args, cwd) { return cp.spawnSync(cmd, args, { cwd, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 }); }
+function git(args, cwd) {
+  const r = sh('git', args, cwd);
+  if (r.error || r.status !== 0) throw new StetError(((r.stderr || '') + '').trim() || `git ${args.join(' ')} failed`);
+  return r.stdout;
+}
+function tgit(args, cwd, d = '') { try { return git(args, cwd); } catch { return d; } }
+const nonEmpty = (s) => String(s || '').split('\n').filter((x) => x.trim() !== '');
+const names = (s) => nonEmpty(s).map((x) => x.trim());
+
+function findRoot(start = process.cwd()) {
+  let d = path.resolve(start);
+  for (;;) {
+    if (fs.existsSync(path.join(d, '.stet'))) return d;
+    const p = path.dirname(d);
+    if (p === d) break;
+    d = p;
+  }
+  return tgit(['rev-parse', '--show-toplevel'], start).trim() || path.resolve(start);
+}
+
+class Repo {
+  constructor(root) { this.root = root; this.dir = path.join(root, '.stet'); }
+  p(...a) { return path.join(this.dir, ...a); }
+  has() { return fs.existsSync(this.dir); }
+  need() { if (!this.has()) throw new StetError('No .stet/ folder found. Run `stet init` in your project first.'); }
+  isGit() { return !!tgit(['rev-parse', '--git-dir'], this.root).trim(); }
+  read(f, d = '') { try { return fs.readFileSync(this.p(f), 'utf8'); } catch { return d; } }
+  write(f, s) { fs.mkdirSync(path.dirname(this.p(f)), { recursive: true }); fs.writeFileSync(this.p(f), s); }
+  json(f, d) { try { return JSON.parse(this.read(f)); } catch { return d; } }
+  wjson(f, o) { this.write(f, JSON.stringify(o, null, 2) + '\n'); }
+  get config() { return { name: path.basename(this.root), protect: [], ignore: [], maxFileKB: 64, checkTimeoutSec: 600, ...this.json('config.json', {}) }; }
+  get locks() { return this.json('locks.json', []); }
+  get scope() { return this.json('scope.json', {}); }
+  tgit(a, d = '') { return tgit(a, this.root, d); }
+  head(full) { return this.tgit(['rev-parse', ...(full ? [] : ['--short']), 'HEAD']).trim(); }
+  branch() { return this.head() ? this.tgit(['rev-parse', '--abbrev-ref', 'HEAD']).trim() : '(no commits yet)'; }
+  rootFile(f) { try { return fs.readFileSync(path.join(this.root, f), 'utf8'); } catch { return null; } }
+}
+
+// ---------- globs ----------
+function globRe(g) {
+  g = String(g).trim().replace(/^\.\//, '');
+  if (g.endsWith('/')) g += '**';
+  let re = '';
+  for (let i = 0; i < g.length; i++) {
+    const ch = g[i];
+    if (ch === '*') {
+      if (g[i + 1] === '*') { i++; if (g[i + 1] === '/') { i++; re += '(?:.*/)?'; } else re += '.*'; } else re += '[^/]*';
+    } else if (ch === '?') re += '[^/]';
+    else re += ch.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+  }
+  return new RegExp('^' + re + '$');
+}
+function matches(file, globs) {
+  return (globs || []).some((g) => globRe(g).test(file) || (!/[*?]/.test(g) && file.startsWith(String(g).replace(/^\.\//, '').replace(/\/$/, '') + '/')));
+}
+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: [] };
+  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 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 (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')) { 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]));
+  return s;
+}
+
+const NOISE = [/(^|\/)node_modules\//, /(^|\/)\.git\//, /(^|\/)(dist|build|\.next|out|coverage|__pycache__|\.venv|venv)\//, /\.(png|jpe?g|gif|webp|ico|pdf|zip|woff2?|ttf|mp4|mov|lock)$/i, /(^|\/)(package-lock\.json|yarn\.lock|pnpm-lock\.yaml)$/, /^\.stet\/(\.cache|context\.md)/];
+function listFiles(r) {
+  let files;
+  if (r.isGit()) files = names(r.tgit(['ls-files', '--cached', '--others', '--exclude-standard']));
+  else {
+    files = [];
+    const walk = (d, rel) => {
+      for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+        if (['node_modules', '.git', 'dist', 'build', '.venv', 'venv'].includes(e.name)) continue;
+        const rp = rel ? rel + '/' + e.name : e.name;
+        if (e.isDirectory()) walk(path.join(d, e.name), rp); else files.push(rp);
+        if (files.length > 20000) return;
+      }
+    };
+    walk(r.root, '');
+  }
+  const ign = r.config.ignore;
+  return files.filter((f) => !NOISE.some((re) => re.test(f)) && !matches(f, ign)).sort();
+}
+
+function changedFiles(r, { base, staged } = {}) {
+  if (!r.isGit()) return [];
+  if (staged) return names(r.tgit(['diff', '--cached', '--name-only']));
+  const set = new Set();
+  if (r.head()) {
+    const b = base && r.tgit(['rev-parse', '--verify', '--quiet', base + '^{commit}']).trim() ? base : 'HEAD';
+    names(r.tgit(['diff', '--name-only', b])).forEach((f) => set.add(f));
+  } else names(r.tgit(['diff', '--cached', '--name-only'])).forEach((f) => set.add(f));
+  names(r.tgit(['ls-files', '--others', '--exclude-standard'])).forEach((f) => set.add(f));
+  return [...set].sort();
+}
+const STET_OWNED = ['.stet/**', 'AGENTS.md', 'CLAUDE.md', 'HANDOFF.md', '.mcp.json'];
+
+// ---------- templates ----------
+function charterTemplate(name, st) {
+  const stack = [...st.langs, ...st.frameworks].join(', ') || 'Describe your stack here';
+  return `# ${name}
+
+## What this is
+<!-- One paragraph: what the product does, for whom, and what stage it is at. -->
+${name} is ...
+
+## Stack
+- ${stack}
+${st.test ? `- Tests: \`${st.test}\`\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.
+- Keep changes inside the current scope. If the task needs more, stop and ask.
+- Run \`stet check\` before saying a task is done, and report the result honestly.
+- Record any architectural decision with \`stet decide\`.
+
+## Never
+- Never rewrite, rename or "clean up" working code outside the task.
+- Never delete or weaken a test, check or validation to make something pass.
+- Never add a dependency, service or env var without saying why.
+- Never invent APIs, files, tables or config. If you are unsure, ask.
+- Never commit secrets, keys or customer data.
+
+## Notes for agents
+<!-- Anything an AI keeps getting wrong in this repo: naming, folders, gotchas. -->
+`;
+}
+
+// ---------- AGENTS.md / CLAUDE.md sync ----------
+const BEGIN = '<!-- stet:begin -->', END = '<!-- stet:end -->';
+function decisionsList(r) {
+  const md = r.read('decisions.md');
+  const out = [];
+  const re = /^## (D-\d+) · (\S+) · (.+)$/gm; let m;
+  while ((m = re.exec(md))) out.push({ id: m[1], date: m[2], title: m[3].trim() });
+  return out;
+}
+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.`;
+}
+function locksBlock(r) {
+  const L = r.locks;
+  if (!L.length) return 'No locked behaviours yet. The human adds them with `stet lock add`.';
+  return `These already work and must keep working:\n\n| ID | Behaviour | Proof (must pass) | Files that affect it |\n|---|---|---|---|\n${L.map((l) => `| ${l.id} | ${l.name} | \`${l.cmd}\` | ${(l.protect || []).map((g) => '`' + g + '`').join(', ') || '—'} |`).join('\n')}\n\nBefore saying any task is done, run \`stet check\`. If a check fails, fix your change. Never edit the test or weaken the check to make it pass.`;
+}
+function agentsBlock(r) {
+  const charter = r.read('charter.md').replace(/^# .*\n+/, '').replace(/<!--[\s\S]*?-->\n?/g, '').trim();
+  const prot = r.config.protect;
+  const ds = decisionsList(r).slice(-15);
+  return `${BEGIN}
+<!-- Generated by Stet from .stet/. Edit .stet/charter.md or use stet commands. Text outside this block is yours and is kept. -->
+# Working agreement for AI coding agents — ${r.config.name}
+
+This is the source of truth for any AI agent working in this repo (Claude Code, Cursor, Codex, Copilot, Windsurf or a chat assistant). Read all of it before changing code. If anything said earlier in a chat conflicts with this file, this file wins.
+
+## Project charter
+${charter.replace(/^## /gm, '### ')}
+
+## Current task scope
+${scopeBlock(r)}
+
+## Locked behaviours
+${locksBlock(r)}
+
+## Protected paths
+${prot.length ? `Do not modify these without explicit approval from the human:\n${prot.map((g) => `- \`${g}\``).join('\n')}` : 'None set.'}
+
+## Decisions already made
+${ds.length ? `Do not reopen these unless the human asks:\n${ds.map((d) => `- **${d.id}** (${d.date}) ${d.title}`).join('\n')}` : 'None yet.'}
+
+## Workflow
+1. Load the current repo state with \`stet context\` (or the MCP tool \`stet_context\`). Trust it over older chat history.
+2. Work only inside the scope above.
+3. Run \`stet guard\` to confirm you only changed in-scope files.
+4. Run \`stet check\` to confirm every locked behaviour still passes.
+5. Record new architectural decisions with \`stet decide "<decision>" --why "<reason>"\`.
+6. Finish with a short summary: what changed, which files, check results and anything you were unsure about.
+${END}`;
+}
+function sync(r) {
+  r.need();
+  const block = agentsBlock(r);
+  const ap = path.join(r.root, 'AGENTS.md');
+  const cur = r.rootFile('AGENTS.md');
+  let next;
+  if (cur == null) next = block + '\n';
+  else if (cur.includes(BEGIN) && cur.includes(END)) next = cur.slice(0, cur.indexOf(BEGIN)) + block + cur.slice(cur.indexOf(END) + END.length);
+  else next = block + '\n\n' + cur;
+  const changed = next !== cur;
+  if (changed) fs.writeFileSync(ap, next);
+  const cl = r.rootFile('CLAUDE.md');
+  if (cl == null) fs.writeFileSync(path.join(r.root, 'CLAUDE.md'), '# Claude Code\n\nThe working agreement for this repo lives in AGENTS.md (maintained by Stet):\n\n@AGENTS.md\n');
+  else if (!cl.includes('@AGENTS.md')) fs.writeFileSync(path.join(r.root, 'CLAUDE.md'), cl.replace(/\s*$/, '') + '\n\n@AGENTS.md\n');
+  return out(changed ? `${OK()} AGENTS.md updated` : `${OK()} AGENTS.md already in sync`, 0, { changed });
+}
+
+// ---------- init ----------
+function init(r, { name, mcp } = {}) {
+  const st = detect(r.root);
+  const nm = name || r.config.name;
+  const made = [], kept = [];
+  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('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');
+  sync(r);
+  const lines = [`${OK()} Stet initialised in ${c.bold(r.root)}`];
+  if (!r.isGit()) lines.push(`${WARN()} This folder is not a git repo. guard, context and handoff work best with git.`);
+  lines.push(`  stack:   ${[...st.langs, ...st.frameworks].join(', ') || 'not detected'}`);
+  lines.push(`  created: ${made.map((f) => '.stet/' + f).join(', ') || 'nothing new'}${kept.length ? c.dim(`  (kept ${kept.length} existing)`) : ''}`);
+  lines.push(`  wrote:   AGENTS.md, CLAUDE.md`);
+  if (mcp) lines.push(mcpInstall(r).text);
+  lines.push('', c.bold('Next:'),
+    `  1. Edit ${c.cyan('.stet/charter.md')} — one paragraph on what this is, plus your rules.`,
+    `  2. Lock what already works:  ${c.cyan('stet lock add "Login works" --cmd "npm test -- auth" --protect "src/auth/**"')}`,
+    `  3. Before each AI task:      ${c.cyan('stet scope set "Add CSV export" --allow "src/export/**,tests/export/**"')}`,
+    `  4. After the AI is done:     ${c.cyan('stet guard && stet check')}`,
+    `  5. Commit .stet/, AGENTS.md and CLAUDE.md so every agent and teammate gets the same rules.`);
+  return out(lines.join('\n'));
+}
+
+// ---------- decisions ----------
+function decide(r, title, { why } = {}) {
+  r.need();
+  if (!title) throw new StetError('Usage: stet decide "<decision>" [--why "<reason>"]');
+  const ds = decisionsList(r);
+  const n = ds.length ? Math.max(...ds.map((d) => +d.id.slice(2))) + 1 : 1;
+  const id = 'D-' + String(n).padStart(3, '0');
+  const md = r.read('decisions.md').replace(/\s*$/, '\n');
+  r.write('decisions.md', `${md}\n## ${id} · ${today()} · ${title.replace(/\n/g, ' ')}\n${why ? why.trim() + '\n' : ''}`);
+  sync(r);
+  return out(`${OK()} Logged ${c.bold(id)}: ${title}`, 0, { id });
+}
+function decisions(r, { all } = {}) {
+  r.need();
+  const ds = decisionsList(r);
+  if (!ds.length) return out('No decisions logged yet.');
+  return out((all ? ds : ds.slice(-10)).map((d) => `${c.violet(d.id)}  ${c.dim(d.date)}  ${d.title}`).join('\n'));
+}
+
+// ---------- locks ----------
+function lockAdd(r, name, { cmd, protect } = {}) {
+  r.need();
+  if (!name || !cmd) throw new StetError('Usage: stet lock add "<behaviour>" --cmd "<command that proves it>" [--protect "glob,glob"]');
+  const L = r.locks;
+  const n = L.length ? Math.max(...L.map((l) => +String(l.id).slice(1) || 0)) + 1 : 1;
+  const l = { id: 'L' + n, name, cmd, protect: splitList(protect), added: today() };
+  L.push(l); r.wjson('locks.json', L); sync(r);
+  return out(`${OK()} Locked ${c.bold(l.id)}: ${name}\n  proof: ${c.cyan(cmd)}${l.protect.length ? `\n  watches: ${l.protect.join(', ')}` : ''}`, 0, l);
+}
+function lockList(r) {
+  r.need();
+  const L = r.locks;
+  if (!L.length) return out('No locked behaviours. Add one with: stet lock add "<behaviour>" --cmd "<command>"');
+  const last = r.json('.cache/last-check.json', { results: [] });
+  return out(L.map((l) => {
+    const res = last.results.find((x) => x.id === l.id);
+    const mark = !res ? c.dim('·') : res.ok ? OK() : BAD();
+    return `${mark} ${c.bold(l.id.padEnd(4))} ${l.name}\n     ${c.dim('$')} ${c.cyan(l.cmd)}${l.protect && l.protect.length ? c.dim('  watches ' + l.protect.join(', ')) : ''}`;
+  }).join('\n'));
+}
+function lockRm(r, id) {
+  r.need();
+  const L = r.locks; const i = L.findIndex((l) => l.id.toLowerCase() === String(id).toLowerCase());
+  if (i < 0) throw new StetError(`No lock with id ${id}. See: stet lock list`);
+  const [l] = L.splice(i, 1); r.wjson('locks.json', L); sync(r);
+  return out(`${OK()} Removed ${l.id}: ${l.name}`);
+}
+function check(r, { only } = {}) {
+  r.need();
+  let L = r.locks;
+  if (only) { const ids = splitList(only).map((s) => s.toLowerCase()); L = L.filter((l) => ids.includes(l.id.toLowerCase())); }
+  if (!L.length) return out(`${WARN()} Nothing to check. Lock a behaviour first: stet lock add "<behaviour>" --cmd "<command>"`);
+  const lines = [c.bold(`Checking ${L.length} locked behaviour${L.length > 1 ? 's' : ''}`)];
+  const results = [];
+  for (const l of L) {
+    const t0 = Date.now();
+    const p = cp.spawnSync(l.cmd, { cwd: r.root, shell: true, encoding: 'utf8', timeout: r.config.checkTimeoutSec * 1000, maxBuffer: 64 * 1024 * 1024, env: { ...process.env, CI: process.env.CI || '1', FORCE_COLOR: '0' } });
+    const ms = Date.now() - t0;
+    const ok = p.status === 0;
+    const all = ((p.stdout || '') + (p.stderr || '')).replace(/\x1b\[[0-9;]*m/g, '').trim().split('\n');
+    const KEY = /(not ok|fail(ed|ure)?\b|error|expected|actual|assert|✗|×|panic|traceback|exception)/i;
+    const SKIP = /^\s*#\s*(fail|pass|tests|suites)\s+\d+|failureType|duration_ms|^\s*code:|^\s*\.\.\.$|^\s*error:\s*\|-?\s*$|^\s*name:\s*'?AssertionError'?\s*$|^\s*operator:/i;
+    const hits = all.filter((x) => KEY.test(x) && !SKIP.test(x)).map((x) => x.trim()).filter((x, i, a) => a.indexOf(x) === i).slice(0, 10);
+    const tail = (hits.length ? hits : all.slice(-12)).join('\n');
+    const cantRun = !ok && (p.status === 127 || /Missing script:|command not found|is not recognized as an internal|ENOENT|No such file or directory.*(\.js|\.py)/i.test(all.join('\n')));
+    results.push({ id: l.id, name: l.name, ok, ms, exit: p.status, cantRun, timedOut: !!(p.error && p.error.code === 'ETIMEDOUT') });
+    lines.push(`${ok ? OK() : cantRun ? WARN() : BAD()} ${c.bold(l.id.padEnd(4))} ${l.name} ${c.dim(`(${(ms / 1000).toFixed(1)}s)`)}${cantRun ? c.yellow('  proof command cannot run') : ''}`);
+    if (!ok) lines.push(c.dim(tail.split('\n').map((x) => '     │ ' + x).join('\n')));
+  }
+  const failed = results.filter((x) => !x.ok);
+  const broken = failed.filter((x) => !x.cantRun), bad = failed.filter((x) => x.cantRun);
+  r.wjson('.cache/last-check.json', { at: new Date().toISOString(), head: r.head(), results });
+  lines.push('');
+  if (bad.length) lines.push(`${WARN()} ${c.yellow(`${bad.map((f) => f.id).join(', ')}: the proof command itself can't run (missing script or command).`)} Fix the lock: stet lock rm ${bad[0].id}, then add it with a command that works (see: npm run).`);
+  if (broken.length) lines.push(`${BAD()} ${c.red(`${broken.length} locked behaviour${broken.length > 1 ? 's' : ''} broken: ${broken.map((f) => f.id).join(', ')}.`)} Fix the change, not the check.`);
+  if (!failed.length) lines.push(`${OK()} ${c.green('All locked behaviours pass.')}`);
+  return out(lines.join('\n'), failed.length ? 1 : 0, { results });
+}
+
+// ---------- scope + guard ----------
+function scopeSet(r, task, { allow } = {}) {
+  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`);
+}
+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'}`)}`);
+}
+function scopeClear(r) { r.need(); r.wjson('scope.json', {}); sync(r); return out(`${OK()} Scope cleared.`); }
+
+function guard(r, { base, staged, warn } = {}) {
+  r.need();
+  if (!r.isGit()) throw new StetError('stet guard needs a git repo.');
+  const s = r.scope, cfg = r.config, L = r.locks;
+  const files = changedFiles(r, { base: base || s.base, staged }).filter((f) => !matches(f, STET_OWNED));
+  const outScope = [], protectedHits = [], lockHits = [];
+  for (const f of files) {
+    if (s.allow && s.allow.length && !matches(f, s.allow)) outScope.push(f);
+    if (matches(f, cfg.protect)) protectedHits.push(f);
+    for (const l of L) if (matches(f, l.protect)) lockHits.push({ f, l });
+  }
+  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}`) : ''));
+  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);
+    const lk = lockHits.filter((x) => x.f === f).map((x) => x.l.id);
+    lines.push(`  ${bad ? BAD() : lk.length ? WARN() : OK()} ${f}${outScope.includes(f) ? c.red('  out of scope') : ''}${protectedHits.includes(f) ? c.red('  protected') : ''}${lk.length ? c.yellow(`  affects ${lk.join(', ')}`) : ''}`);
+  }
+  const violations = [...new Set([...outScope, ...protectedHits])];
+  const lockIds = [...new Set(lockHits.map((x) => x.l.id))];
+  lines.push('');
+  if (violations.length) lines.push(`${BAD()} ${c.red(`${violations.length} file${violations.length > 1 ? 's' : ''} outside scope or protected.`)} Revert, or widen the scope on purpose.`);
+  if (lockIds.length) lines.push(`${WARN()} Changes touch locked behaviour ${lockIds.join(', ')}. Run: stet check --only ${lockIds.join(',')}`);
+  if (!violations.length) lines.push(`${OK()} ${c.green(files.length ? 'All changes are inside scope.' : 'No changes yet.')}`);
+  return out(lines.join('\n'), violations.length && !warn ? 1 : 0, { files, violations, lockIds });
+}
+
+// ---------- context pack ----------
+function readCapped(r, f, maxKB) {
+  try {
+    const full = path.join(r.root, f);
+    const st = fs.statSync(full);
+    if (!st.isFile()) return null;
+    const buf = fs.readFileSync(full);
+    if (buf.includes(0)) return '(binary file skipped)';
+    const s = buf.toString('utf8');
+    return s.length > maxKB * 1024 ? s.slice(0, maxKB * 1024) + `\n… (truncated at ${maxKB} KB)` : s;
+  } catch { return null; }
+}
+function tree(files, cap = 400) {
+  const shown = files.slice(0, cap);
+  const outL = []; let prev = [];
+  for (const f of shown) {
+    const parts = f.split('/');
+    let i = 0; while (i < parts.length - 1 && prev[i] === parts[i]) i++;
+    for (let j = i; j < parts.length - 1; j++) outL.push('  '.repeat(j) + parts[j] + '/');
+    outL.push('  '.repeat(parts.length - 1) + parts[parts.length - 1]);
+    prev = parts;
+  }
+  if (files.length > cap) outL.push(`… and ${files.length - cap} more files`);
+  return outL.join('\n');
+}
+const fence = (f) => ({ ts: 'ts', tsx: 'tsx', js: 'js', jsx: 'jsx', py: 'python', go: 'go', rs: 'rust', rb: 'ruby', json: 'json', md: 'md', yml: 'yaml', yaml: 'yaml', sql: 'sql', css: 'css', html: 'html', sh: 'bash' }[f.split('.').pop()] || '');
+function context(r, { files, changed, diff, maxKB } = {}) {
+  r.need();
+  const cfg = r.config; maxKB = +maxKB || cfg.maxFileKB;
+  const all = listFiles(r);
+  const g = r.isGit();
+  const status = g ? nonEmpty(r.tgit(['status', '--short'])).filter((l) => !/\.stet\/(\.cache|context\.md)/.test(l)) : [];
+  const parts = [];
+  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.`);
+  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\`\`\``);
+  parts.push(`## File tree\n\`\`\`\n${tree(all)}\n\`\`\``);
+  let pick = [];
+  if (files) pick = all.filter((f) => matches(f, splitList(files)));
+  if (changed) pick = [...new Set([...pick, ...changedFiles(r, { base: r.scope.base }).filter((f) => !matches(f, STET_OWNED))])];
+  if (pick.length) {
+    let budget = 400 * 1024;
+    const blocks = [];
+    for (const f of pick) {
+      const s = readCapped(r, f, maxKB);
+      if (s == null) { blocks.push(`### ${f}\n(deleted or unreadable)`); continue; }
+      if (budget - s.length < 0) { blocks.push(`### ${f}\n(skipped: context size budget reached)`); continue; }
+      budget -= s.length;
+      blocks.push(`### ${f}\n\`\`\`${fence(f)}\n${s.replace(/\s*$/, '')}\n\`\`\``);
+    }
+    parts.push(`## File contents\n${blocks.join('\n\n')}`);
+  }
+  if (diff && g) {
+    let d = r.head() ? r.tgit(['diff', r.scope.base || 'HEAD']) : '';
+    if (d.length > 200 * 1024) d = d.slice(0, 200 * 1024) + '\n… (diff truncated)';
+    parts.push(`## Diff since scope was set\n\`\`\`diff\n${d.trim() || '(no changes)'}\n\`\`\``);
+  }
+  return out(parts.join('\n\n') + '\n', 0, { files: all.length, included: pick.length });
+}
+function copyToClipboard(text) {
+  const tries = process.platform === 'darwin' ? [['pbcopy', []]] : process.platform === 'win32' ? [['clip', []]] : [['wl-copy', []], ['xclip', ['-selection', 'clipboard']], ['xsel', ['--clipboard', '--input']]];
+  for (const [cmd, args] of tries) { const p = cp.spawnSync(cmd, args, { input: text }); if (!p.error && p.status === 0) return true; }
+  return false;
+}
+
+// ---------- handoff ----------
+function handoff(r) {
+  r.need();
+  const cfg = r.config, st = detect(r.root), all = listFiles(r), g = r.isGit() && r.head();
+  const ext = {}; for (const f of all) { const e = f.includes('.') ? f.split('.').pop().toLowerCase() : '(none)'; ext[e] = (ext[e] || 0) + 1; }
+  const top = {}; for (const f of all) { const t = f.includes('/') ? f.split('/')[0] + '/' : '(root files)'; top[t] = (top[t] || 0) + 1; }
+  const envEx = ['.env.example', '.env.sample', '.env.template'].map((f) => r.rootFile(f)).find((x) => x != null);
+  const envKeys = envEx ? nonEmpty(envEx).filter((l) => /^[A-Z_][A-Z0-9_]*=/.test(l.trim())).map((l) => l.trim().split('=')[0]) : [];
+  const hot = {};
+  if (g) for (const f of names(r.tgit(['log', '-200', '--name-only', '--pretty=format:']))) if (all.includes(f) && !matches(f, STET_OWNED)) hot[f] = (hot[f] || 0) + 1;
+  const charter = r.read('charter.md').replace(/<!--[\s\S]*?-->\n?/g, '').replace(/^# .*\n+/, '').replace(/^## /gm, '### ').trim();
+  const ds = decisionsList(r);
+  const decMd = r.read('decisions.md').split(/\n(?=## D-)/).slice(1).map((b) => b.replace(/^## /, '#### ').trim()).join('\n\n');
+  const L = r.locks, s = r.scope;
+  const sorted = (o, n) => Object.entries(o).sort((a, b) => b[1] - a[1]).slice(0, n);
+  const md = `# Handoff — ${cfg.name}
+
+Generated by Stet ${VERSION} on ${today()}. Regenerate any time with \`stet handoff\`; it is built from the repo, not from memory.
+
+| | |
+|---|---|
+| Repository | ${g ? (r.tgit(['remote', 'get-url', 'origin']).trim() || 'no remote set') : 'not a git repo'} |
+| Branch / commit | ${g ? `\`${r.branch()}\` @ \`${r.head()}\`` : '—'} |
+| History | ${g ? `${r.tgit(['rev-list', '--count', 'HEAD']).trim()} commits since ${r.tgit(['log', '--reverse', '--format=%as']).split('\n')[0]} · ${nonEmpty(r.tgit(['shortlog', '-sn', 'HEAD'])).length} contributor(s)` : '—'} |
+| Stack | ${[...st.langs, ...st.frameworks].join(', ') || 'not detected'} |
+| Size | ${all.length} tracked files |
+
+## 1. Product charter
+${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.'}
+${envKeys.length ? `\nEnvironment variables needed (names only, from the example env file):\n${envKeys.map((k) => '`' + k + '`').join(' · ')}` : ''}
+
+## 3. Architecture at a glance
+**Entry points:** ${st.entry.length ? st.entry.map((x) => '`' + x + '`').join(', ') : 'not detected'}
+
+**Top-level layout**
+| Folder | Files |
+|---|---|
+${sorted(top, 20).map(([k, v]) => `| \`${k}\` | ${v} |`).join('\n')}
+
+**Languages by file count:** ${sorted(ext, 8).map(([k, v]) => `${k} ${v}`).join(' · ')}
+${st.deps.length ? `\n**Key dependencies:** ${st.deps.slice(0, 30).map((x) => '`' + x + '`').join(', ')}` : ''}
+${Object.keys(hot).length ? `\n**Most-changed files (last 200 commits)** — where the active work and the risk are:\n${sorted(hot, 10).map(([k, v]) => `- \`${k}\` — ${v} change${v === 1 ? '' : 's'}`).join('\n')}` : ''}
+
+## 4. What must not break
+${L.length ? `| ID | Behaviour | Proof | Watches |\n|---|---|---|---|\n${L.map((l) => `| ${l.id} | ${l.name} | \`${l.cmd}\` | ${(l.protect || []).join(', ') || '—'} |`).join('\n')}\n\nRun them all with \`stet check\`.` : 'No locked behaviours recorded yet.'}
+${cfg.protect.length ? `\n**Protected paths:** ${cfg.protect.map((x) => '`' + x + '`').join(', ')}` : ''}
+
+## 5. Decisions and why (${ds.length})
+${decMd || 'None recorded.'}
+
+## 6. Work in progress
+${s.task ? `Current task: **${s.task}** (allowed: ${s.allow.map((x) => '`' + x + '`').join(', ')})` : 'No task scope is open.'}
+${g ? `\nRecent commits:\n\`\`\`\n${r.tgit(['log', '--oneline', '--no-decorate', '-12']).trim()}\n\`\`\`` : ''}
+
+## 7. First day checklist for a new engineer or CTO
+- [ ] Read sections 1, 4 and 5 of this document (charter, what must not break, decisions).
+- [ ] Get it running locally with the commands in section 2.
+- [ ] Run \`stet check\` and confirm every locked behaviour passes on your machine.
+- [ ] Read \`AGENTS.md\`. It is what the AI agents follow, so it is also the team's working agreement.
+- [ ] Skim the most-changed files in section 3.
+- [ ] Note anything here that is wrong or missing and record it with \`stet decide\` or in the charter.
+`;
+  return out(md);
+}
+
+// ---------- status ----------
+function status(r) {
+  r.need();
+  const cfg = r.config, s = r.scope, L = r.locks, ds = decisionsList(r);
+  const last = r.json('.cache/last-check.json', null);
+  const lines = [c.bold(`Stet · ${cfg.name}`) + c.dim(`  ${r.isGit() ? r.branch() + ' @ ' + (r.head() || 'no commits') : 'not a git repo'}`)];
+  lines.push(`  scope      ${s.task ? s.task + c.dim('  (' + s.allow.join(', ') + ')') : c.dim('none set')}`);
+  lines.push(`  locks      ${L.length}${last ? `  last check ${last.results.every((x) => x.ok) ? c.green('passed') : c.red('failed: ' + last.results.filter((x) => !x.ok).map((x) => x.id).join(', '))} ${c.dim(last.at.slice(0, 16).replace('T', ' ') + (last.head && last.head !== r.head() ? ' (older commit)' : ''))}` : c.dim('  never checked')}`);
+  lines.push(`  decisions  ${ds.length}${ds.length ? c.dim('  latest: ' + ds[ds.length - 1].title) : ''}`);
+  const ag = r.rootFile('AGENTS.md') || '';
+  lines.push(`  AGENTS.md  ${ag.includes(agentsBlock(r)) ? c.green('in sync') : c.yellow('out of date — run stet sync')}`);
+  if (r.isGit() && s.task) { const gd = guard(r, { warn: true }); lines.push(`  guard      ${gd.data.violations.length ? c.red(gd.data.violations.length + ' out-of-scope file(s)') : c.green(gd.data.files.length + ' changed, all in scope')}`); }
+  return out(lines.join('\n'));
+}
+
+// ---------- git hook ----------
+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
+$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)'}.`);
+}
+
+// ---------- MCP config ----------
+function mcpInstall(r) {
+  const fp = path.join(r.root, '.mcp.json');
+  let j = {}; try { j = JSON.parse(fs.readFileSync(fp, 'utf8')); } catch {}
+  j.mcpServers = { ...(j.mcpServers || {}), stet: { command: 'npx', args: ['-y', 'stet-cli', 'mcp'] } };
+  fs.writeFileSync(fp, JSON.stringify(j, null, 2) + '\n');
+  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 };

package/lib/mcp.js

@@ -0,0 +1,60 @@
+'use strict';
+// Minimal MCP server over stdio (newline-delimited JSON-RPC 2.0). No dependencies.
+const core = require('./core');
+
+const TOOLS = [
+  { name: 'stet_context', description: 'Get the live state of this repository: working agreement (charter, scope, locked behaviours, decisions), recent commits, uncommitted changes and the file tree. Call this at the start of every task and whenever you are unsure what exists. Optionally include file contents.',
+    inputSchema: { type: 'object', properties: { files: { type: 'array', items: { type: 'string' }, description: 'Paths or globs whose contents to include, e.g. ["src/auth/**"]' }, changed: { type: 'boolean', description: 'Include contents of files changed since the scope was set' }, diff: { type: 'boolean', description: 'Include the diff since the scope was set' } } } },
+  { 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_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'] } },
+];
+
+function callTool(name, a = {}) {
+  const r = new core.Repo(core.findRoot(process.env.STET_ROOT || process.cwd()));
+  switch (name) {
+    case 'stet_context': return core.context(r, { files: a.files, changed: a.changed, diff: a.diff });
+    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_decide': return core.decide(r, a.decision, { why: a.why });
+    default: throw new core.StetError('Unknown tool: ' + name);
+  }
+}
+
+function serve(input = process.stdin, output = process.stdout) {
+  core.setColor(false);
+  const send = (m) => output.write(JSON.stringify(m) + '\n');
+  let buf = '';
+  input.setEncoding('utf8');
+  input.on('data', (chunk) => {
+    buf += chunk;
+    let i;
+    while ((i = buf.indexOf('\n')) >= 0) {
+      const line = buf.slice(0, i).trim(); buf = buf.slice(i + 1);
+      if (!line) continue;
+      let msg; try { msg = JSON.parse(line); } catch { send({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } }); continue; }
+      handle(msg, send);
+    }
+  });
+}
+
+function handle(msg, send) {
+  const { id, method, params = {} } = msg;
+  const reply = (result) => id !== undefined && send({ jsonrpc: '2.0', id, result });
+  const fail = (code, message) => id !== undefined && send({ jsonrpc: '2.0', id, error: { code, message } });
+  try {
+    if (method === 'initialize') return reply({ protocolVersion: params.protocolVersion || '2025-06-18', capabilities: { tools: {} }, serverInfo: { name: 'stet', version: core.VERSION }, instructions: 'Stet keeps you inside the human\'s agreed scope. Call stet_context at the start of a task, stet_guard and stet_check before saying it is done.' });
+    if (method === 'ping') return reply({});
+    if (method === 'tools/list') return reply({ tools: TOOLS });
+    if (method === 'tools/call') {
+      try { const r = callTool(params.name, params.arguments || {}); return reply({ content: [{ type: 'text', text: r.text }], isError: r.code !== 0 }); }
+      catch (e) { return reply({ content: [{ type: 'text', text: 'stet: ' + e.message }], isError: true }); }
+    }
+    if (method && method.startsWith('notifications/')) return;
+    return fail(-32601, 'Method not found: ' + method);
+  } catch (e) { return fail(-32603, e.message); }
+}
+
+module.exports = { serve, handle, TOOLS };

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "stet-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.2",
+  "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"
+  },
+  "main": "lib/core.js",
+  "files": [
+    "bin",
+    "lib",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "claude-code",
+    "cursor",
+    "codex",
+    "mcp",
+    "agents.md",
+    "regression",
+    "context",
+    "cli"
+  ],
+  "license": "MIT",
+  "author": "Shamaz Khan",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shamazkhan/stet.git"
+  },
+  "homepage": "https://github.com/shamazkhan/stet#readme",
+  "bugs": {
+    "url": "https://github.com/shamazkhan/stet/issues"
+  }
+}