carveout 0.1.1 → 0.2.0

package/README.md

@@ -1,435 +1,241 @@
 <h1 align="center">carveout</h1>
 
 <p align="center">
-  <strong>Zero-trust handoff for your codebase.</strong><br>
-  They see one folder. None of their code runs until you've read it.
+  <strong>Open-source a feature, not your codebase.</strong><br>
+  Let a contractor, an outside contributor or an AI agent work on your closed repository.<br>
+  They get one folder that builds and tests on its own. Their work comes back as a patch that runs none of their code.
 </p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/carveout"><img src="https://img.shields.io/npm/v/carveout?style=flat-square&label=npm" alt="npm version"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="MIT license"></a>
-  <a href="SKILL.md"><img src="https://img.shields.io/badge/Claude_Code-skill-D97757?style=flat-square" alt="Claude Code skill"></a>
+  <a href="skills/carveout/SKILL.md"><img src="https://img.shields.io/badge/Claude_Code-skill-D97757?style=flat-square" alt="Claude Code skill"></a>
+  <a href="https://skills.sh/lunox-work/carveout"><img src="https://img.shields.io/badge/skills.sh-npx_skills_add_lunox--work%2Fcarveout-111?style=flat-square" alt="skills.sh"></a>
   <a href="#limits"><img src="https://img.shields.io/badge/TypeScript-repositories-3178C6?style=flat-square" alt="TypeScript repositories"></a>
 </p>
 
 <p align="center">
-  <img src="assets/hero.png" width="100%" alt="Zero-trust handoff for your codebase. A contractor sees 0.7% of the repository's source (median of 8 slices of a 245k-line TypeScript repository), and 0 lines of their code run before you read the patch: CI and hook files, manifests, lockfiles, deleted or weakened tests, new network or disk access and files outside the slice are kept out.">
+  <img src="assets/hero.png" width="100%" alt="Open-source a feature, not your codebase. What they see: 0.7% of a 245k-line repository, the median slice (11% with tests and pure code). What runs on your machine: 0 lines of their code; CI, hooks, lockfiles, weakened tests, code that spots a test run, new network or disk access and files outside the slice are held. What comes back: 52 of 52 real commits replayed through a slice come back as patches that apply.">
 </p>
 
 <table>
 <tr>
-<td align="center" width="25%"><h3>under 1%</h3>of the repository<br>is what they see<br><sub>median 0.7% of 245k lines</sub></td>
-<td align="center" width="25%"><h3>0 lines</h3>of their code run<br>to make the patch<br><sub>it is read, never executed</sub></td>
-<td align="center" width="25%"><h3>52 of 52</h3>returned patches<br>applied to the repository<br><sub>real commits, sliced and merged back</sub></td>
-<td align="center" width="25%"><h3>89%</h3>still apply after<br>the repository moved on<br><sub>every one typechecks</sub></td>
+<td align="center" width="25%"><h3>0.7%</h3>of the repository<br>is what a slice shows<br><sub>median of 8 slices of 245k lines; 11% with tests and pure code</sub></td>
+<td align="center" width="25%"><h3>0 lines</h3>of their code run<br>on your machine<br><sub>the patch is read, never run; checks run in a container with no network</sub></td>
+<td align="center" width="25%"><h3>52 of 52</h3>replayed commits<br>come back and apply<br><sub>49 byte-identical; 89% with <code>--3way</code> after the repo moved</sub></td>
+<td align="center" width="25%"><h3>6 of 6</h3>agents in a sealed folder<br>shipped their task<br><sub>each patch passed the owner's hidden tests</sub></td>
 </tr>
 </table>
 
 <p align="center">
-  <a href="#handing-a-slice-to-a-contractor">Handoff</a> •
+  <a href="#before--after">Before/After</a> •
+  <a href="#install">Install</a> •
+  <a href="#how-it-works">How it works</a> •
+  <a href="#what-comes-back-and-what-is-held">What comes back</a> •
+  <a href="#proof">Proof</a> •
   <a href="#commands">Commands</a> •
-  <a href="#also-checking-a-change-in-the-repository">Impact and gate</a> •
-  <a href="#experiments">Experiments</a> •
   <a href="#limits">Limits</a> •
-  <a href="experiments/RESULTS.md">RESULTS.md</a>
+  <a href="docs/REFERENCE.md">Reference</a>
 </p>
 
-Hand one part of a closed TypeScript repository to an outside contractor,
-and take their work back, without showing them the rest.
+Named for the corporate carve-out: one unit split off from a company so it
+can stand on its own. carveout does that for one feature of a repository,
+and takes the work back when it is done.
 
-You name a file or a folder. carveout copies it, and what it imports up to
-a depth you choose, into a new folder at the same paths. Every module it
-imports from the rest of the repository becomes a `.d.ts` stub with a
-recording mock behind it, so the folder installs, builds and tests on its
-own: the contractor gets the slice's source and the declarations of what it
-uses, never the bodies behind them. When the folder comes back,
-`carveout patch` turns the edits into a patch for the repository, runs none
-of the contractor's code, and keeps out what they should not slip in: CI
-and hook files, manifests and lockfiles, deleted or weakened tests, new
-files in other packages.
+---
 
-```sh
-# maintainer, at the repository's root
-npx -y carveout plan  apps/api/src/billing --depth 1 --with-tests   # what the folder would hold; writes nothing
-npx -y carveout cut   apps/api/src/billing --depth 1 --with-tests --public --out ../billing-slice
-npx -y carveout check ../billing-slice          # npm ci, build, test, as the contractor will
+## Before / After
 
-# contractor: npm ci, edit, npm test, send the folder back
+<table>
+<tr>
+<td width="50%">
+
+### 🔓 Without carveout: they get the repo
 
-# maintainer, on the folder that came back
-npx -y carveout status ../billing-slice         # does the repository still match the cut?
-npx -y carveout patch  ../billing-slice --output billing.patch   # runs none of its code
-git apply --3way billing.patch
-# or both, with a check: carveout merge ../billing-slice --into . --verify "npm test"
 ```
+$ git clone git@github.com:acme/closed-repo
+709 files · 245,456 lines of TypeScript
+every package, infra/, .github/workflows/
+their branch runs CI with your secrets
+```
+
+</td>
+<td width="50%">
 
-Use it to:
+### 🔒 With carveout: they get one folder
 
-- let a contractor, an outside contributor or an agent you do not trust
-  with the rest work on one part of a closed repository, and take the work
-  back as a patch that is checked before anything runs it
-  ([below](#handing-a-slice-to-a-contractor));
-- work on one package of a monorepo without installing or building the
-  others: a slice installs in about a third of the time and an eighth of
-  the disk;
-- see what a module really depends on, and what depends on it;
-- make a minimal reproduction of one module.
+```
+$ carveout handoff \
+    packages/jira/src/selection-jql.ts
+Verdict: ready: it installs, builds, and its
+  tests pass before any edit
+Tests: 15 of 15 test(s) pass before any edit
+Shows 15 files, 2,980 lines
+Names: 3 rename(s) hide the repository's
+```
 
-The same import graph also checks a change made inside the repository,
-yours or a coding agent's: `carveout impact` names what it reaches and the
-tests to run, and `carveout gate` holds weakened tests and CI or config
-edits, also as a Claude Code Stop hook
-([below](#also-checking-a-change-in-the-repository)).
+</td>
+</tr>
+<tr>
+<td width="50%">
+
+### ✅ The work comes back
+
+```
+$ carveout patch ../returned --output change.patch
+carveout: 2 changed, 0 new and 0 deleted files
+$ git apply change.patch && npm test -w packages/jira
+ℹ tests 165
+ℹ pass 165
+ℹ fail 0
+```
+
+</td>
+<td width="50%">
+
+### 🚫 A shortcut does not
+
+```
+$ carveout patch ../returned
+carveout: kept out:
+  packages/jira/src/selection-jql.ts,
+  could pass a test without the code
+  passing it (process.execArgv matched
+  against a test runner)
+exit 6
+```
+
+</td>
+</tr>
+</table>
 
-## Handing a slice to a contractor
+**Same task. 15 files out of 709. The shortcut held before anything ran
+it.**
 
-For a contractor or contributor who must not see the rest of a closed
-repository. The maintainer cuts and later merges; the contractor only works
-in the folder.
+A real hand-off on [sandbox-factory](https://github.com/lunox-work/sandbox-factory),
+2026-11-11. The 15 files are the entry point, its test, and 13 pure modules
+copied so that test runs on real code. Everything else the slice touches is
+a `.d.ts` stub with a recording mock: declarations, never bodies. Those 13
+modules were pricing code. `plan` lists every copied file before anything is
+written, and `--private` keeps a folder out: here that shows 245 lines, and 7
+tests then fail on the mocks before any edit. You choose.
+
+## Install
 
 ```sh
-# maintainer, at the repository's root
-carveout plan  packages/api/src/quote.ts --depth 1 --with-tests --whole-package --copy-pure
-carveout cut   packages/api/src/quote.ts --depth 1 --with-tests --whole-package --copy-pure \
-               --public --out ../quote-slice
-carveout check ../quote-slice                 # read what it holds before sending it
-# contractor: npm ci, edit, npm test, send the folder back
-# maintainer, on the folder that came back
-carveout patch ../returned --output quote.patch   # runs none of its code
-less quote.patch                              # read all of it before anything runs it
-git switch -c contrib/quote && git apply --3way quote.patch
-carveout impact --base HEAD                   # the importers and tests the contractor never saw
-# then a PR: CI decides
+npx skills add lunox-work/carveout -g
 ```
 
-What carveout holds to:
-
-- **The folder.** It holds the slice's source as it is, and stubs of what
-  the slice imports from the rest: the declarations of the names it uses
-  (a one-line barrel included), never their bodies or comments. With
-  `--public` (or `"public": true` in the configuration), literal values are
-  widened and the folder names neither the maintainer's checkout nor the
-  files outside the slice that import it. `--private <path>` keeps a module
-  out even when the walk reaches it, `--copy-pure` included. `--copy-pure`
-  copies more of the repository (the pure code the slice runs) so the
-  contributor's tests run against it rather than against mocks: leave it
-  off, or mark that code private, where it must stay closed. `plan` and
-  `cut` list the source copied from outside the entry points by folder,
-  with its lines, tests not counted: each folder there is a `--private`
-  decision to make before the folder is sent.
-- **The folder that comes back.** Nothing in it is trusted. `patch` and
-  `apply` refuse a `carveout.json` that names a path outside the folder or
-  a `.git` path, or lists as the slice's a file the repository does not
-  hold at those bytes, and work against the checkout given with `--repo`
-  (or the current directory), which must hold the cut's commit. `patch`
-  runs none of the folder's code.
-- **The hand-off policy.** The patch carries edits to the slice's files and
-  new files in the slice's packages. It leaves out, names, and exits 6 on:
-  new files in other packages (a cut module's folder among them);
-  protected paths (CI workflows, hooks, `.vscode`, `.devcontainer`,
-  `package.json`, lockfiles, `.npmrc`, `.env*`, Dockerfiles, Makefiles,
-  `*.sh`, `CODEOWNERS`, `carveout.config.json`); deleted tests; and edited
-  tests that remove or rewrite an assertion, skip or focus (`.only`) a
-  test, or leave an assertion unreachable or in a `catch` that swallows it
-  (an expected value changed may be the change itself, or a test bent to
-  pass: the maintainer reads it); and a script, new or edited, that gains
-  a reach it did not have: Node's disk, network or process modules, a
-  service SDK, `fetch`, `eval`, the environment, or a module or global
-  named by a computed value (a returned test that reads the closed source
-  and sends it out is one). `--allow <path|glob>` lets a reviewed one
-  through. `merge` applies nothing while any is refused. The policy reads
-  syntax, not intent: a new runner configuration (`vitest.config.ts`), or
-  code that does harm with only the reach its file already had, passes it.
-- **Running what came back.** The contributor's tests, and every new file
-  the patch carries, are code that runs beside the whole repository, the
-  part the slice kept closed included. A branch pushed to the repository
-  runs CI with the repository's secrets and network, which a fork's pull
-  request does not: code there can read the source and send it out. Read
-  the whole patch before anything runs it, or run its first CI with no
-  secrets and no outbound network. `check --isolated` gives the folder a
-  scratch HOME and npm cache and no install scripts, and `merge --verify`
-  a scratch HOME and only the variables named with `--verify-env`:
-  neither is a sandbox, and `merge --verify` runs in the full checkout.
-
-What it does not promise:
-
-- **What a pass in the folder covers is stated.** `plan`, `cut` and
-  BOUNDARY.md name every test that runs the slice's code and stays in the
-  repository, and why (not asked for, another package's, Jest, the file
-  limit). When none is in the folder, a pass means the code builds and
-  keeps its exports, nothing more.
-- **Passing in the slice is a pre-check, not the merge gate.** The slice's
-  tests run against mocks of everything it cuts. A test that needs a cut
-  module's real behaviour fails at the slice's baseline and is not counted,
-  and a test that imports `carveout/` to make a mock answer stays in the
-  folder: the change comes back without it, and `patch` says how many. In
-  the experiments, verdicts in the slice and after the merge agreed in 74%
-  of cases, nearly all disagreements in the safe direction (the slice
-  failed, the repository passed). `--copy-pure` turns most such baselines
-  green, and the surface check catches a changed export the importers in
-  other packages rely on; neither runs those importers. Those figures come
-  from earlier CLIs: the model-run benchmarks have not been run again since
-  `--copy-pure`, the surface check and the barrel-chain rule. The
-  repository's CI decides, once the patch has been read.
-- **The slice's own source is the contributor's to read.** Choose the
-  entry points and `--private` paths with that in mind; `plan` lists every
-  file before anything is written.
-
-## What a cut holds
+In Claude Code, the repository is also a plugin marketplace:
+`/plugin marketplace add lunox-work/carveout`, then
+`/plugin install carveout@carveout`. It holds two skills:
+[`carveout`](skills/carveout/SKILL.md), the hand-off, and
+[`carveout-gate`](skills/carveout-gate/SKILL.md), `impact` and `gate` for a
+change made in the repository. The plugin also bundles the `lunox` MCP server
+(`.mcp.json`), Lunox's hosted platform: Claude Code asks you to sign in on
+first use (`/mcp`), and signed out the skills run locally as before.
+
+Then ask your coding agent (Claude Code, Codex, Cursor, or any agent that
+loads skills): _"hand `src/billing` to a contractor"_. It plans the slice,
+shows you what goes out, and cuts it once you agree. Without a skill, use the
+CLI:
 
+```sh
+npx -y carveout handoff src/billing/quote.ts --task task.md --out ../quote-slice
 ```
-billing-slice/
-  apps/api/src/billing/...   the slice, copied at its repository paths
-  packages/db/src/index.d.ts a stub of what the slice uses from a cut module
-  packages/db/src/index.js   its recording mock
-  carveout/packages/stripe/  a mock package for a service SDK
-  carveout/mock.js           the mock runtime: recordedCalls(), mockImplementation()
-  carveout/tests/            an interface test: every export outside code imports
-  carveout/surface/          those exports' declarations at the cut, and the type
-                             check npm test holds them to
-  BOUNDARY.md                an index: the tests that run the slice's code (in the
-                             folder, and left behind with why), the modules it
-                             imports from outside, and the exports outside code
-                             takes from it
-  carveout.json              the cut: hashes, cuts, packages, rewrites, blockers
-  package.json, tsconfig.json, package-lock.json, carveout.env
+
+Needs Node 22.12+ and a TypeScript repository (npm, pnpm or Yarn; `node:test`
+or Vitest). Code that came back runs only in Docker; without it, carveout
+runs none of it unless you pass `--no-sandbox`.
+
+## Try it in 60 seconds
+
+```sh
+# maintainer, at the repository's root
+npx -y carveout plan    apps/api/src/billing --depth 1 --with-tests   # what the folder would hold; writes nothing
+npx -y carveout handoff apps/api/src/billing --task task.md --out ../billing-slice
+
+# contractor: npm ci, edit, npm test, send the folder back
+
+# maintainer, on the folder that came back
+npx -y carveout patch ../billing-slice --output billing.patch   # runs none of its code
+less billing.patch                                               # read all of it
+git switch -c contrib/billing && git apply --3way billing.patch  # then a PR: CI decides
 ```
 
-- **Stubs** are emitted by the TypeScript compiler from the cut modules'
-  own declarations, and narrowed to the names the slice uses.
-- **Workspace packages** are stubbed from their source rather than
-  installed, unless the cut follows them (`--follow-workspaces`): then an
-  import of one is an import of its source file, copied or cut like any
-  module. Either way, a file in another package that imports the slice by
-  the package's name is one of its importers.
-- **Installed packages** are those the repository pins from the public
-  registry. Each comes with its `@types` and its required peers, at the
-  repository's versions.
-- **Mock packages** stand in for service SDKs (payments, cloud, databases,
-  queues, email, HTTP clients, LLM SDKs) and for private-registry packages.
-- **Import rewrites.** Path aliases, workspace imports and bundler-style
-  extensionless imports become relative paths Node resolves. Each is
-  recorded, and `patch` undoes it.
-- **Assets.** Stylesheets and images a module imports are copied, and load
-  in Node as their path. `import.meta.glob` and `import.meta.env` work
-  under Node.
-- **The repository's checks.** The compiler options that only reject
-  code (`strict`, `noUnusedLocals` and the like) come from the
-  repository's tsconfig. `noImplicitAny` too, unless the slice does not
-  compile under it with its stubs and untyped packages, which the cut says. Node's types come at the repository's version.
-  When the package's own test sets coverage thresholds, `npm test` holds
-  the source files you add to them, and fails, as the package's script
-  does, on a file you add that no test loads (`assert-all-covered`).
-- **The public surface.** Every export code outside the slice imports
-  must stay exported (the interface test) and keep its type: `npm test`
-  type-checks `carveout/surface/check.ts`, which holds each such value to
-  its type at the cut and each such type to its shape both ways, and
-  names the export whose type changed. Enums and classes with private
-  members are not checked; a check that fails before any edit is not
-  counted.
-- **Credentials.** A credentials file is never copied. A credential found
-  in anything the cut would write, a `--copy` folder or the resolved
-  lockfile included, stops the cut: nothing is written.
-
-The plan and the cut read the repository and never run its code. The cut
-fetches package types from the public registry with install scripts off,
-and resolves a lockfile; when the repository has an npm lockfile, the
-slice starts from its locked versions. `--offline` skips both.
-
-## What the walk follows
-
-- **Names, not whole files.** Importing `a` from a barrel brings the barrel
-  and the module that declares `a`, at the barrel's depth. The barrel's
-  other re-exports are cut.
-- **Code, not types.** A module the slice takes only types from
-  (`import type`, or an interface or type alias by name) is cut to its
-  stub and never copied.
-- **Files read by path.** `new URL("./worker.ts", import.meta.url)` and
-  `join(__dirname, "get.sql")` copy the file. A folder read by path, or such
-  a file left outside the slice, is a `path_read` blocker.
-- **Modules named to a test runner** (`vi.mock`, `jest.requireActual`,
-  `require.resolve`) are cut, not followed. Their specifiers are rewritten
-  like imports.
-- **The file budget.** When it runs out, `plan` lists the files it left out.
-- **The whole package**, with `--whole-package`: every file of the entry
-  points' package the imports reach comes along at any depth, so the cut
-  falls at package and service boundaries, and a sibling module is copied
-  rather than stubbed. A barrel's re-exports come only when they supply a
-  name the slice asks of it. Imports into other packages still stop at the
-  depth.
-- **Barrel chains.** A test that takes a slice name through barrels
-  (`src/index.ts` → `pricing/index.ts` → `pricing/weight.ts`) is a test of
-  the slice: `--with-tests` brings it and the whole chain, each barrel cut
-  to what it forwards from the slice.
-- **A test's helpers.** A test brought along by `--with-tests` brings what
-  it imports at runtime from its own package, or from a test folder
-  anywhere (`test/`, `__mocks__/`, `fixtures/`): a fake copied is a test
-  that passes, a fake stubbed is one that fails before any change.
-- **Private paths** (`--private <path>`, or `private` in the
-  configuration) are never copied: wherever the walk reaches one it is
-  cut and stubbed, with literal values widened.
-- **Pure code**, with `--copy-pure`: a module the slice runs from outside
-  it is copied rather than mocked, past the depth and across packages,
-  when nothing its runtime imports reach outside the slice imports a
-  service SDK, Node's disk, network or process modules, reads the
-  environment or a path, or is private. A mocked validator or error
-  class answers with more mocks, and the tests that use it fail before
-  any change; copied, they run as in the repository. Through a barrel,
-  only the modules that supply the names come. The copied code is the
-  contributor's to read: `plan` lists it.
-
-Only the files the walk needs are parsed. Files that may import the slice
-are found by name first, and the compiler confirms each one.
+## How it works
 
-## Commands
+<p align="center">
+  <img src="assets/flow.png" width="100%" alt="One folder out, one checked patch back. Out: carveout handoff on a 709-file repository sends 15 files; the rest are .d.ts stubs and mocks, names in pseudonyms, 15 of 15 tests pass before any edit. Their work: a contractor, contributor or agent runs npm ci, edits, and npm test passes 17 of 17. Back: carveout patch runs none of it; 2 files come back and the repository's tests pass 165 of 165; code that matched process.execArgv against a test runner is held.">
+</p>
 
-| Command                                  | Does                                                                                                                                                                                                           |
-| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `carveout plan <entry>...`               | Lists the files, cuts, importers, packages, environment and blockers; the lines the cut shows, by why each file is there; every test that runs the code, in the folder or left behind and why. Writes nothing. |
-| `carveout cut <entry>... --out <dir>`    | Writes the folder. Exits 2 if it was written with blockers; writes nothing if it would carry a credential.                                                                                                     |
-| `carveout check <dir>`                   | Runs `npm ci`, `npm run build` and `npm test` in a scratch copy; records the tests that fail on the mocks. `--isolated` for a folder that came back.                                                           |
-| `carveout status <dir>`                  | Says whether a cut now would write the same folder, and names what changed. Exits 4 if stale.                                                                                                                  |
-| `carveout patch <dir>`                   | Prints the edits as a patch for the repository (`--output <file>`), with full blob ids for `git apply --3way`. Runs none of the folder's code; keeps out what the hand-off policy refuses (exit 6).            |
-| `carveout merge <dir> --into <checkout>` | Patches, applies with `--3way` in the checkout you name, and runs `--verify <cmd>` there with a scratch HOME and only the `--verify-env` variables. Applies nothing on a refusal (exit 6).                     |
-| `carveout apply <dir> <patch>`           | Brings a patch for the repository into the folder, imports rewritten; `--stubs` adds the stubs it needs. A module the patch adds past the cut's reach joins the folder as an entry, with its tests.            |
-
-Options for `plan` and `cut`:
-
-- `--repo <root>` (default `.`)
-- `--depth N` (default 3)
-- `--max-files N` (default 40)
-- `--with-tests`, which also brings the tests outside the slice that import
-  it (`*.test.*`, `*.spec.*`, `__tests__/`) and run on `node:test` or
-  Vitest (imported, or its globals in a package that depends on Vitest and
-  not Jest), directly or through barrels outside the slice that re-export
-  from it; such a barrel comes along, its other re-exports cut, and so do
-  the test's own helpers. `npm test` in the folder runs them. When the
-  file budget cannot hold them all, the tests nearest the entry points
-  come first: those that take names the entry points declare, whatever
-  barrel they import through, ahead of those that take names declared
-  further out. Without a
-  lockfile Vitest is mocked like any package; cut with `--install vitest`.
-- `--whole-package`, `--follow-workspaces`, `--copy-pure` (which follows
-  the workspaces too) and `--private <path>` (see above; `--private` takes
-  a path, a folder or a glob, more than once).
-- `--json`
-
-A `carveout.config.json` at the repository's root sets the same for every
-cut, so the owner decides once where a slice may follow and what it keeps
-out: `{"wholePackage": true, "followWorkspaces": true, "private":
-["packages/core/src/pricing/**"], "copy": ["packages/db/drizzle"],
-"widenLiterals": true, "public": true, "copyPure": true}`. A flag overrides a boolean; the
-lists are joined. With any `private` path, or `public`, `widenLiterals` is
-on unless the file says otherwise.
-
-Options for `cut` only:
-
-- `--mock <pkg>` and `--install <pkg>`, which take precedence over the
-  defaults. A package whose class a carried test patches by prototype
-  (`S3Client.prototype.send = ...`) is installed without being asked: a
-  mock has no prototype to patch, and such a test never reaches the
-  service. So is one whose class the code tests with `instanceof`
-  (`error instanceof Anthropic.APIError`): a mock narrows nothing, and the
-  folder would not build;
-- `--copy <dir>`, which copies a folder the code reads by a name the walk
-  cannot follow (a migrations folder) beside the slice. Its files are the
-  repository's: an edit to one is in the patch;
-- `--live <pkg>`, which keeps a service package real: installed and typed
-  as the repository has it, with the environment its importers read left
-  out of `carveout.env` for the shell to supply, so the code's own
-  defaults apply otherwise. For tests that need the service itself, such
-  as a database driver against a local server;
-- `--widen-literals`, which writes `string` in stubs in place of literal
-  values. A constant the stub reads as a type (`type Kind = (typeof
-KINDS)[number]`) keeps its name-like strings (`"github"`, `"draft"`):
-  they are that type's members, and widened, the slice would stop checking
-  the code that relies on them. Its numbers, URLs and sentences widen;
-- `--public`, for a folder handed to someone outside: literals widened,
-  and neither the checkout's path or folder name nor the files outside the
-  slice that import it written (each importer is named by its package
-  folder; compiler messages name files from the repository's root). The
-  commands that need the repository then take `--repo`, defaulting to the
-  current directory;
-- `--offline`.
-
-Options for `patch`, `status`, `apply` and `merge`: `--repo <checkout>`,
-the repository to work against (it must hold the cut's commit; `merge`
-uses `--into`). For `patch` and `merge`: `--allow <path|glob>`, which lets
-a path the hand-off policy refuses through. For `merge`: `--verify-env
-<name>`, an environment variable the verify command is given.
-
-Exit codes: 0 done, 1 refused or failed, 2 written with blockers (`cut`)
-or a step failed (`check`, `merge`, `impact --run`; `gate --hook` on a
-hold), 3 nothing to patch, 4 stale (`status`), 5 the edits reach past the
-slice, 6 the hand-off policy kept files out (`patch`, `merge`) or held a
-change (`gate`).
+- **Out.** You name a file or a folder. carveout copies it, and what it
+  imports up to a depth you choose, at the same paths. Every module it
+  imports from the rest becomes a `.d.ts` stub with a recording mock, so the
+  folder installs, builds and tests on its own.
+- **Nameless.** A hand-off is written in pseudonyms: the repository's
+  package names, scope, remote, authors and your Git identity are renamed
+  (`LunoxCart` becomes `AcmeCart`). Only your receipt maps them back, and it
+  never leaves your machine.
+- **Ready before it ships.** `check` runs the folder as the contractor will.
+  It says the folder is ready (its tests pass before any edit) or names the
+  tests that fail on the mocks and what would run them on real code.
+- **Back.** `carveout patch` turns the folder's edits into a patch in your
+  names. It trusts nothing in the folder: the receipt decides what a patch
+  may carry. It runs none of their code.
+
+## What comes back, and what is held
+
+| Comes back                                       | Held, named, exit 6 until you `--allow` it                                 |
+| ------------------------------------------------ | -------------------------------------------------------------------------- |
+| Edits to the slice's files                       | CI workflows, hooks, Dockerfiles, Makefiles, `.env*`, manifests, lockfiles |
+| New files in the slice's packages                | Deleted tests, and tests that lose, move or rewrite an assertion           |
+| New tests, where the package's runner finds them | `.skip`, `.only`, and code that spots a test run (`NODE_ENV`, argv, stack) |
+| A package you add, named with its pin            | New reach: disk, network, process, environment, `eval`, a missing package  |
+| Your names, put back                             | New `@ts-ignore` or `eslint-disable`, and files in other packages          |
+
+The policy reads syntax, not intent: code that special-cases a test's own
+inputs passes it. Read the whole patch before anything runs it, and run its
+first CI with no secrets. The full policy is in the
+[reference](docs/REFERENCE.md#handing-a-slice-to-a-contractor).
+
+## Proof
+
+- **What a slice shows.** Over 8 slices of a 245k-line repository, a
+  default cut copies a median of 0.7% of the source (0.03 to 2.4%). With the
+  hand-off's tests and pure code, 11% (0.3 to 24%). Stub declarations come
+  on top and are not counted
+  ([hero-exposure.mjs](experiments/hero-exposure.mjs)).
+- **The round trip.** 52 real commits replayed through a slice all come back
+  as patches that apply, 49 byte-identical. On a repository that moved on,
+  27% apply plain and 89% with `git apply --3way`.
+- **Agents in a folder.** Six agents, each given only a public hand-off
+  folder, delivered their tasks. Each patch applied in the repository's
+  names and passed the owner's hidden acceptance tests.
+- **Folders that stand alone.** Ten of eleven slices from three
+  repositories install, build and test on their own with the hand-off's
+  flags. The eleventh fails on a narrowed inferred type ([Limits](#limits)).
+- **What it does not win.** A slice does not make an agent cheaper or
+  better: it read 17 to 24% more input and passed hidden tests 5 to 10
+  points less often than the same agent in the whole repository. A pass in
+  the slice matched the verdict after the merge in 74% of replays, nearly
+  every miss the safe way (the slice failed, the repository passed). The
+  slice is a pre-check; your CI is the gate.
+
+Pre-registered, with the raw data: [experiments/RESULTS.md](experiments/RESULTS.md).
 
 ## Also: checking a change in the repository
 
-The import graph a slice is cut from also answers two questions about a
-change made inside the repository, yours or a coding agent's, with no slice
-involved: what does it reach, and what should a reviewer read before it
-lands? `gate` applies the hand-off policy above to that change.
+The same import graph checks a change made inside the repository, yours or
+a coding agent's:
 
 ```sh
-npx -y carveout impact                      # what the uncommitted change reaches
-npx -y carveout impact --base main --run    # since main, and run just those tests
-npx -y carveout gate --base main            # weakened tests, CI or config edits, suppressions
+npx -y carveout impact                 # what the change reaches, and the tests to run
+npx -y carveout gate --base main       # weakened tests, CI or config edits, suppressions
 ```
 
-| Command                       | Does                                                                                                                                                                                          |
-| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `carveout impact [<file>...]` | What a change in the repository reaches: importers, changed exports and who takes them, the tests to run and their commands. `--base`, `--depth`, `--run` (exit 2 on a failing test command). |
-| `carveout gate`               | Holds a change's weakened or deleted tests, protected paths, check configuration and new suppressions (exit 6). `--base`, `--scope`, `--allow`, `--hook`.                                     |
-
-`impact` and `gate` read the change from Git: the base (default `HEAD`)
-against the working tree, untracked files included. Neither runs the
-repository's code, but for `impact --run`.
-
-**`carveout impact`** reports:
-
-- **Importers**: every file that imports a changed module, directly or
-  through others, found by name and confirmed by the compiler (aliases,
-  workspace package names, barrels, `vi.mock`). It follows names, as the
-  slice walk does: a barrel carries a change only through the names it
-  forwards from the changed module, and a module only through its exports
-  whose declarations reach a changed declaration. With a base, only the
-  exports the diff reaches start the search; named files start with all of
-  theirs.
-- **Exports**: each export of a changed module whose type changed or that
-  is gone, as the TypeScript checker prints it at the base and now, one
-  level of members deep, and the files that take it.
-- **Tests**: the tests among the importers, each with its runner
-  (`node:test`, Vitest or Jest; otherwise the package's own `npm test`),
-  and one command per package that runs just them. The commands run only
-  installed binaries (`npx --no`).
-- **`--run`** runs those commands one at a time, in the repository, with
-  your environment, and exits 2 when one fails. `--depth N` bounds the hops;
-  `--json` gives it all as data.
-
-On sandbox-factory (1,288 files) it takes under 1.5 s. A change to one
-function of `packages/core/src/stages.ts` selects 21 of the repository's
-241 tests, among them the API test that pins that function's message, two
-hops away; naming the whole file selects 156.
-
-**`carveout gate`** holds for review, and exits 6 on any:
-
-- protected paths (CI workflows, hooks, manifests, lockfiles, `.env*`,
-  Dockerfiles; the hand-off policy's list above);
-- configuration a check reads, when edited: `tsconfig*.json`, ESLint,
-  Biome, Vitest, Jest, coverage settings;
-- a deleted test, and a test whose assertions were removed or rewritten,
-  skipped, focused with `.only`, made unreachable (an early `return`,
-  `if (false)`), or wrapped in a `catch` that swallows their failure;
-- new suppressions in a script: `@ts-ignore`, `@ts-expect-error`,
-  `eslint-disable`, coverage ignores;
-- with `--scope <path|glob>`, any file outside it.
-
-A hold is a question for a reviewer, not a verdict: a change asked to
-alter a behaviour rewrites the assertion that held it. `--allow
-<path|glob>` lets a reviewed file through. As a Claude Code Stop hook,
-`--hook` sends the holds back to the agent (exit 2) once per stop, asking
-it to undo what the task did not ask for and to name the rest in its reply:
+`gate` also works as a Claude Code Stop hook. It sends its holds back to the
+agent once per stop:
 
 ```json
 {
@@ -445,99 +251,46 @@ it to undo what the task did not ask for and to name the rest in its reply:
 }
 ```
 
-On a patch that came back from a slice, `git apply` it on a branch and run
-`carveout impact --base HEAD` (no `--run`) before anything runs it: it
-names the importers and tests the contractor never saw.
-
-## Tested on
-
-Thirteen real slices from three TypeScript repositories, sandbox-factory
-among them. They range from 1 to 173 files, and cover Node services, React
-components and a whole Vite app's `src` at depth 1, with npm workspaces and
-path aliases. Every one installed, built and passed its interface test with
-`carveout check`.
-
-One needed a second cut. An auth module's installed package loads an
-optional peer at runtime, `drizzle-orm`. The first cut listed it among the
-optional peers and `check` named it; cutting again with
-`--install drizzle-orm` passed.
-
-Walking by name rather than by file made three of them smaller, with the
-rest unchanged: 4 files to 2, 3 to 1, and 19 to 11. The modules left out
-were ones they imported only types from, now stubs. All thirteen still pass
-`check`.
-
-The lazy graph walks as the whole graph does: identical results in 722
-walks over five repositories, cal.com and n8n among them. On n8n (24k
-files) the median walk takes 2.3 s against 13.7 s for the whole graph. A
-slice whose files have common names can read most of the repository, and
-then takes as long.
-
-On n8n (pnpm, catalogs, Vitest globals), a one-module slice installs,
-builds and passes `check`, where it once stopped at the install on a
-`catalog:` pin; with `--with-tests` it carries five Vitest tests, and its
-build then fails on limits named below (an `override` of a mocked base
-class, `never[]` under the relaxed `noImplicitAny`).
-
-## Experiments
-
-`experiments/` holds the pre-registered experiments and their data
-([RESULTS.md](experiments/RESULTS.md)).
-
-- **What a slice shows.** Over the eight sandbox-factory slices in
-  `slices.json`, a default cut copies a median of 0.7% of the repository's
-  245k lines of TypeScript as source (0.03 to 2.4%); with
-  `--whole-package --with-tests --copy-pure`, 11% (0.3 to 24%)
-  ([hero-exposure.mjs](experiments/hero-exposure.mjs)).
-- **Agents in a slice (Phases 5 to 8).** An agent given a slice instead of
-  the repository did not get cheaper or better: it read 17 to 24% more
-  input, passed hidden tests 5 to 10 points less often, and a weaker model
-  did as well in the repository as in a slice. A full-repository agent read
-  a median of two files outside the slice. The slice's measured wins are
-  the ones without a model: setup at 0.35× the time and 0.12× the disk, and
-  a bounded view. That is why the slice is for someone who must not see
-  the rest, not a way to make an agent cheaper, and why `impact` and
-  `gate` work in the repository itself.
-- **`status` (E1).** Over 345 later commits it never said `current` when a
-  fresh cut differed.
-- **Three-way patches (E2).** Applied to a repository that had moved, a
-  patch applied plain in 27% of cases and with `git apply --3way` in 89%.
-  Every three-way result typechecked.
-- **Co-change hints in `plan` (E3).** Precision was too low, so they were
-  dropped.
-- **Graph time (E4).** The graph of a 24k-file monorepo takes 12 s, down
-  from 7.5 minutes before a fix that leaves the graph identical. A cache
-  across runs was not built: it could not reach a 3× speedup.
+## Commands
+
+| Command                       | Does                                                                           |
+| ----------------------------- | ------------------------------------------------------------------------------ |
+| `carveout handoff <entry>...` | Cut for someone outside, check it, and say whether it is ready to send         |
+| `carveout plan <entry>...`    | List what a folder would hold, cut and show. Writes nothing                    |
+| `carveout cut <entry>...`     | Write the folder                                                               |
+| `carveout check <dir>`        | `npm ci`, build and test it as the contractor will; returned folders in Docker |
+| `carveout patch <dir>`        | Turn the folder's edits into a patch, holding what the policy refuses          |
+| `carveout merge <dir>`        | Patch, apply, and run `--verify` in a container                                |
+| `carveout status <dir>`       | Say whether the repository still matches the cut                               |
+| `carveout refresh <dir>`      | Bring the repository's new commits into the folder, merged with the work       |
+| `carveout widen <dir>`        | Cut again with more entry points, keeping the work                             |
+| `carveout impact`             | What a change reaches: importers, changed exports, tests to run                |
+| `carveout gate`               | Hold weakened tests, CI and config edits, and new suppressions                 |
+| `carveout login`              | Optional: sign in to the Lunox platform; a token in `~/.lunox/credentials`     |
+| `carveout whoami`             | Print the account, workspace and token expiry signed in with                   |
+| `carveout logout`             | Delete the saved platform token                                                |
+
+Every option: [reference](docs/REFERENCE.md#commands). Only `login`, `whoami`
+and `logout` talk to the Lunox platform; every other command is local and needs
+no account.
 
 ## Limits
 
-- **Languages.** Stubs are extracted from TypeScript only. A JavaScript
-  source in a slice is reported as `language_unsupported`.
-- **Inferred types.** A stub can be narrower than the source when a type is
-  inferred from a package carveout could not read. The cut reports this; it
-  does not hide it.
-- **Lockfiles.** Peers and locked versions are read from an npm
-  `package-lock.json`. pnpm and Yarn repositories fall back to the versions
-  in their package.json files; a `catalog:` pin takes the catalog's
-  version (`pnpm-workspace.yaml`, or `catalog(s)` in the root
-  package.json). A pnpm lock entry with no tarball URL shows a package is
-  public only when its integrity equals the public registry's for that
-  version (checked online; offline it is mocked). Such folders resolve
-  peers as pnpm and Yarn do (`legacy-peer-deps`).
-- **Test runners.** `node:test` and Vitest. A Jest test is named as left
-  behind, never run.
-- **Folders named like build output.** Files under `build/`, `dist/`,
-  `vendor/` and `third_party/` are not parsed: a source folder named
-  `build` is copied when reached, but its own imports are not followed.
-- **What `impact` can miss.** It follows imports, not runtime: a module
-  loaded by a computed name, a file read by path, or configuration a test
-  reads is not traced, and a test it does not list can still fail. Inside a
-  module it traces names by the identifiers each top-level statement uses,
-  which errs toward more. A type is compared one level of members deep: a
-  change inside a named type shows on that type's own module. Its
-  `node:test` command for TypeScript uses Node's type stripping, which does
-  not resolve path aliases; such a package's own test script is the one to
+- **TypeScript only.** A JavaScript source in a slice is reported, not
+  stubbed.
+- **`node:test` and Vitest.** A Jest test is named as left behind, never
   run.
+- **Mocks only record calls.** A change that needs a cut module's real
+  behaviour needs `--copy-pure`, `--live <package>` or a wider cut
+  (`carveout widen`).
+- **More green, more shown.** Copying pure code turns red baselines green
+  and shows more of the repository. `plan` lists every file first.
+- **Syntax, not intent.** The policy is a reader's checklist, not a proof.
+  Read the patch; the repository's CI decides.
+- **Docker** (or Podman) runs code that came back. Without it, nothing runs
+  but with `--no-sandbox`, which runs it as you.
+
+All of them: [reference](docs/REFERENCE.md#limits).
 
 <!-- Keep this section and AGENTS.md the same. -->
 
@@ -562,8 +315,9 @@ the person:
 
 For a slice, run `npx -y carveout plan <entry> --depth 1` first. Show the
 person what the slice would hold and what it cuts, and agree the entry
-points and the depth with them. Then `cut` and `check`, and report the
-check's result as it is.
+points and the depth with them. Then `cut` and `check` (or `handoff`, both
+in one, with `--task` for the work and its acceptance), and report the
+verdict as it is: ready, tests that fail on the mocks, or no tests.
 
 For a change in the repository, run `npx -y carveout impact` (add
 `--base <branch>` for committed work) and report the exports, importers and
@@ -597,14 +351,31 @@ What to tell them, accurately:
 - `--copy-pure` copies the pure code the slice runs instead of mocking
   it, so the folder's tests pass before any change; it shows the
   contributor more of the repository, which `plan` lists.
+- `--public` also writes the folder in pseudonyms: the names the
+  repository goes by (packages, remote, authors, the maintainer's Git
+  identity, `--name`) are renamed under a table only the maintainer's
+  receipt holds, and `patch` renames the work back. A name left behind
+  blocks the cut; report it, and add it with `--name` or `pseudonyms` in
+  the configuration. Never send the receipt.
 - For someone outside the repository, cut with `--public`, take the folder
   back with `carveout patch` (it runs none of the folder's code and keeps
   out CI, hook, manifest and lockfile files, new files in other packages,
-  deleted tests and code that newly reaches the disk, network or
+  deleted or bent tests, code that could pass a test without the code
+  under test, and code that newly reaches the disk, network or
   environment), read the whole patch before anything runs it (its
   tests and new files are code beside the closed repository, and a branch
   pushed there gets CI's secrets and network), then let the repository's
   CI judge the change: a pass in the slice is a pass against mocks.
+- `carveout check` and `merge --verify` run a folder that came back only
+  after the hand-off policy has read it, and only in a container (Docker)
+  that mounts nothing of the machine but a copy, with no network but for an
+  install with scripts off. When the container cannot run, they run
+  nothing; `--no-sandbox` runs the folder's code as the person, with their
+  files and network: say so before passing it.
+- For a job long enough that the repository moves, `carveout refresh`
+  brings its commits into the folder, merged into the work (an overlap is
+  named, never overwritten), and a patch after it carries the work alone;
+  `carveout widen` cuts the folder again, wider, with the work in it.
 - `carveout check` passing means the folder installs, builds, loads every
   export outside code uses and keeps their types. It tests the slice's
   behaviour only when the cut was made with `--with-tests`, and then only
@@ -616,3 +387,7 @@ What to tell them, accurately:
   can still fail. The repository's CI decides.
 - `gate` names what a reviewer should read; it does not judge. A rewritten
   assertion may be the change that was asked for.
+
+## License
+
+MIT. See [LICENSE](LICENSE) and [NOTICE.md](NOTICE.md).