@graftsync/skill 0.1.0 → 0.1.2

package/SKILL.md

@@ -97,15 +97,31 @@ When asked to capture a modification as a graft (new, or migrating an existing p
 2. **Write the intent first,** with the person who owns the modification if you can: *Why*,
    the *Invariants* (observable behaviors, one per bullet), *Where to look* (by behavior), and
    *Anchors* (what the variant matches on and why).
-3. **Write the variant.** For `patch`: run `pnpm patch <pkg>@<installed>`, make the change in the
-   printed directory, then run `pnpm patch-commit <dir> --patches-dir <tmp>`. Move the generated
-   file onto the scaffolded `variants/v<major>.patch`. `pnpm patch-commit` may also write a
-   version-pinned entry to `package.json`; the next step replaces it.
+3. **Write the variant.** For `patch`, make the change in the installed package
+   (`node_modules/<pkg>`), then run `graft capture <id>`: it writes the difference from the
+   published package as the variant (replacing the scaffold stub), and refuses binary changes.
+   **With pnpm**, don't edit `node_modules` in place (its files are hard links into the shared
+   store): run `pnpm patch <pkg>@<installed>`, edit the printed directory, `pnpm patch-commit
+   <dir> --patches-dir <tmp>`, and move the generated file onto `variants/v<major>.patch`
+   (`pnpm patch-commit` may also write a `package.json` entry; the next step replaces it).
 4. **Apply it:** `graft apply`. This points the package manager at the
    variant, reinstalls, and re-checks anchors.
 5. **Write the oracle** so it fails before the modification and passes after. Check that it
    fails without the graft. An oracle that can't fail proves nothing. Test the Invariants,
    plus at least one pre-existing behavior the graft must not break.
+   - **Browser oracles** (Playwright etc.) fail on uncaught page errors, **`console.error`**
+     messages, and failed (5xx) requests. Frameworks catch errors and only log them:
+     Angular's `ErrorHandler`, React error boundaries, Vue's `errorHandler`. Listening only
+     for page errors lets a broken page pass.
+   - **Assert something visible that depends on the graft,** not only "no errors": a page can
+     fail to render without throwing.
+   - **Clean up what you start:** stop a dev server on *every* exit (`process.on('exit', …)`),
+     because `process.exit` skips `finally` blocks and leaves the port taken.
+   - **Test the code path, not the whole stack,** when the rest isn't what the graft changes.
+     For a dependency's browser behavior, load it through the dev server (e.g. a one-line
+     module importing it) instead of rendering pages through a framework's dev SSR.
+   - **Cover the modes the bug lives in.** A dev-only bug needs a `dev` mode; a production
+     build may behave differently (e.g. Vite replaces `process.env` only there).
 6. **Prove it:** `graft verify <id>`, then `graft sync` (green).
 7. **Find the variant's real range:** `graft replay <id>` checks every published version.
    Record what you learn in *History*.
@@ -199,6 +215,8 @@ When asked to capture a modification as a graft (new, or migrating an existing p
   fetch it from there. Never push it unless the user asks.
 - A target can be an upstream commit between releases: `--version 22.3.0-next.3+<sha>` (the
   version part is matched against variant ranges; use upstream's version at that commit).
+- To create one in a fork that is the product: `graft add <id> --package <name> --mechanism fork
+  --in-place --version <upstream version or version+commit>` from the fork's checkout.
 - **In place** (variant `{ "ref": "@worktree", "base": "@verified" }`): never write a new
   variant. A green sync puts the new `verified` only in the result branch; adopt it with
   `git fetch <repo> <ref> && git read-tree -u --reset FETCH_HEAD`. On the `-agent` branch,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graftsync/skill",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Agent skill (SKILL.md) teaching coding agents the graft sync loop.",
   "license": "MIT",
   "repository": {