vinta-ai-workflows 0.2.0-alpha3 → 0.2.0-alpha4

package/skills/vinta-derive-skills/resources/foundation-skills/deslop-comments/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: deslop-comments
+description: Rewrite code comments and docs touched during the current conversation into Simple English, stripping AI-slop / AI-lingo vocabulary and negative framing. Use when the user says "deslop these comments", "clean up the comments we just wrote", "rewrite this in plain English", or after a review flags comments as convoluted/AI-sounding. Comment-only - never changes function names, APIs, or behavior.
+---
+
+# Deslop comments
+
+Rewrites comments and doc blocks into short, direct Simple English. This is a comment-only pass: no renames, no logic changes, no behavior changes.
+
+## Scope
+
+Default scope is **files the current task actually created or edited** - find the candidate set with `git diff --name-only` / `git status --short` against the base the conversation started from. If the user names specific files, a directory, or a Pull Request instead, use that scope.
+
+Do not expand scope to a file just because the agent `Read` it or reviewed it in passing - a debugging or review session routinely reads many unrelated files, and reading one is not authorization to rewrite its comments. If there is no edited-file set and no explicit scope from the user, ask which files to cover.
+
+## What counts as slop
+
+Rewrite a comment if it has any of:
+
+1. **Dense, multi-clause sentences** that try to explain everything at once instead of one idea per sentence.
+2. **Negative / before-state framing** - describing removed code, or leading with "not X" when X was never the point. Keep "not X, it's Y" only for a genuine edge case, a non-obvious gotcha, or bug-fix rationale worth flagging; otherwise state the current behavior directly.
+3. **AI buzzwords** in place of plain software engineering vocabulary. Common offenders and their replacements:
+   - `gate` / `gates` / `gating` → "check", "decides whether to show...", "authentication check", "feature check"
+   - `guard` → "check" / "prevent"
+   - `backstop` → "handles the case where..." / "protects us either way"
+   - `load-bearing` → "useful"
+   - `predicate` → "helper"
+   - `presentational` (component) → "this component only displays the result"
+   - "flattens to a bare new Error" → "turns into a plain new Error"
+   - `harness` → name the concrete thing: "test setup", "test wrapper", "fixture", "mock server", or "runner"
+   - `realm` → "environment", "runtime", or "context" (unless it's the precise JS-realm technical term)
+   - `landed` → "implemented"
+   - `mint` → "created"
+   - `leverage` → "use"
+   - `utilize` → "use"
+   - `surface` → "show" / "return" / "report"
+   - `plumb` / `wire` → "pass" / "connect" / "call"
+   - `broker` → "handle" / "route" / name the service/helper (keep broker if that's the concept name in some architecture, library, service, etc.)
+   - `canonical` → "shared" / "standard"
+   - `churn` → "unnecessary changes"
+   - `invariant` → "rule" / "condition" / "constraint" / or something like "state that must stay true"
+
+     Do not apply this as a blind blacklist. Keep the original word when it is the precise domain term, especially for security, type-system, React, database, FHIR, or JavaScript runtime concepts. For example, `opaque` is a precise security/API term for an id, token, or string whose structure and meaning a caller must not depend on ("recipient is an opaque viewer-supplied string; never log it"); it is not on the replacement list above, so leave it — "generic" would drop that contract.
+4. **Undocumented return shapes.** A function returning an object or union should say what each field/variant means, not just that it "returns a result."
+5. **Any other AI-slop or AI-lingo words, framing, structure.**
+
+## What to leave alone
+
+- Function, type, and API names - this is a comment-only pass.
+- Log strings and error messages shown to users.
+- Generated files (e.g. `*.gen.ts`, Prisma client output).
+- Genuine security markers or contracts written as caps-negatives (`NEVER log PHI`, `Does NOT upsert`) - these are useful warnings, not slop.
+- User-facing UI copy (JSX text nodes rendered to the browser) - that's product copy, not a code comment.
+- Already-clear one-liners that don't exhibit any of the problems above. Don't rewrite for the sake of rewriting.
+
+## Process
+
+1. Build the file list per Scope above.
+2. For each file, read every comment/doc block (`//`, `/* */`, `/** */`, `#`, `%`, depending on the language) and check it against "What counts as slop." Skip anything covered by "What to leave alone."
+3. Rewrite in place with `Edit`. Prefer one idea per sentence. When a function's return type is a union or object with meaningful fields, spell out what each branch/field means using the comment body or JSDoc (or similar) if it's a project pattern.
+4. After editing, confirm the diff is comment-only: `git diff -- <files>` should show no code-line changes, only comment text.
+5. Run the project's lint/typecheck on touched files (e.g. `pnpm biome check <files>`, `pnpm --filter <pkg> typecheck`) to confirm nothing broke.
+6. Summarize what changed in 1-2 sentences - don't restate every line edited.
+
+## Example
+
+Bad (dense, negative framing, buzzwords):
+```
+// Server-to-server auth gate. Fail closed if the token is unconfigured.
+try {
+   if (!verifyServiceAuth(request)) { ... }
+}
+```
+
+Good (Simple English, positive framing, no AI-lingo structure):
+```
+// Server-to-server authentication check. Deny the request if the token is unconfigured.
+try {
+   if (!verifyServiceAuth(request)) { ... }
+}
+```
+
+Bad:
+```
+// NOTE: this forward-block is a UI courtesy only, not a per-step gate.
+// `currentStepIndex` derives from the current URL path — not from saved
+// progress — so navigating to a later step's URL directly bypasses it
+// entirely. The template deliberately ships no per-step route guards
+// (forks may want different ordering/skipping rules); the integrity
+// backstop is the server-side readiness check at intake completion,
+// which refuses to finalize while any step is missing.
+const canNavigateToStep = useCallback(...)
+```
+
+Good:
+```
+// This limits forward navigation in the UI only. `currentStepIndex` comes from
+// the current URL path, not from saved progress, so visiting a later step's URL
+// directly still works. The template intentionally ships no per-step route
+// checks, since forks may want different ordering or skipping rules. The real
+// safeguard is the server-side check at intake completion, which refuses to
+// finalize while any step is missing.
+const canNavigateToStep = useCallback(...)
+```
+
+Bad:
+```
+// Throttle first — cheapest gate. Bounds Argon2 CPU amplification and
+// request flooding on this public endpoint (best-effort, per-instance).
+const rate = await checkRateLimit(getClientKey(request))
+```
+
+Good:
+```
+// Check the rate limit first, since it's the cheapest check to run. Bounds
+// Argon2 CPU amplification and request flooding on this public endpoint.
+const rate = await checkRateLimit(getClientKey(request))
+```
+
+Bad:
+```
+/**
+ * Whether the patient may finalize their intake: every required step must be
+ * validly filled and one of the payment steps must have a saved response.
+ * Server-authoritative — `completeIntake` enforces the same rule, so a client
+ * skipping this check cannot complete a partial intake.
+ *
+ * Required steps are validated (not presence-checked) so a Save-for-later draft
+ * counts as still-missing: the patient is sent back to the earliest unfinished
+ * step (e.g. Demographics) rather than skipped past it to a later one.
+ */
+export async function getIntakeReadiness(headers: Headers): Promise<IntakeReadiness> { ... }
+```
+
+Good:
+```
+/**
+ * Returns whether the patient can finalize their intake: every required step
+ * must pass its schema, and one of the payment steps must have a saved
+ * response. `completeIntake` enforces the same rule on the server, so a
+ * client cannot complete a partial intake by skipping this check. A
+ * Save-for-later draft counts as missing, which sends the patient back to
+ * the earliest unfinished step (e.g. Demographics) instead of skipping past
+ * it. In the returned object, `ready` tells whether the intake can be
+ * completed, and `missingSteps` lists the keys of the steps still missing.
+ */
+export async function getIntakeReadiness(headers: Headers): Promise<IntakeReadiness> { ... }
+```

package/skills/vinta-derive-skills/resources/foundation-skills/prepare-worktree/SKILL.md

@@ -203,7 +203,7 @@ If the **Plan inspection** step inferred the plan doesn't touch any of these: sy
 
 Symlinking + threading the worktree path through prompts keeps *cooperative* agents in the worktree, but it's not a guarantee: a buggy agent (often a smaller model spawned for a phase) can resolve an absolute path back to the **main checkout** and silently write there. Those writes never reach the worktree's commit — they sit as uncommitted thrash in the main checkout, and the "missing" edits read as a silent agent failure. Prompt instructions don't stop it; they rely on the agent's goodwill.
 
-The deterministic, **harness-agnostic** fix is to confine the *process* (not the tool) at the OS filesystem layer: make the main checkout read-only for any command run inside the sandbox, regardless of which agent CLI issues the writes. The bundled [scripts/sandbox-run.sh](scripts/sandbox-run.sh) does this — `sandbox-exec` on macOS, `bwrap` (bubblewrap) on Linux.
+The deterministic fix is to confine the *process* (not the tool) at the OS filesystem layer: make the main checkout read-only for any command run inside the sandbox, regardless of which agent CLI issues the writes. The bundled [scripts/sandbox-run.sh](scripts/sandbox-run.sh) does this — `sandbox-exec` on macOS, `bwrap` (bubblewrap) on Linux. **This process-wrapping model works for runtimes that spawn subagents as subprocesses** (`codex exec`, a `claude -p` child, a custom runner). Runtimes that run subagents **in-process** — notably claude-code's Task tool, where there's no child command to wrap — use the harness-config guard in [In-process runtimes (claude-code)](#55a--in-process-runtimes-claude-code) instead.
 
 **Model: deny-main, allow-rest.** The whole filesystem stays writable EXCEPT the main checkout, with the worktree (and the shared `.vinta-ai-workflows` dir) punched back to writable — even though the worktree usually lives *under* the main checkout (`.claude/worktrees/<name>/`). This deliberately does **not** lock `HOME` / caches / `/tmp`, so package managers, build tools, and test runners behave exactly as unsandboxed. The only thing the cage blocks is a write to the main checkout's own tracked tree — which is exactly the bug.
 
@@ -236,6 +236,36 @@ Escape hatch: `VINTA_SANDBOX=off` makes the wrapper a transparent pass-through (
 - The existing `deps_change=true` → copy/reinstall logic already gives the worktree its own writable `node_modules/` when a phase installs deps; non-churn phases keep the read-only symlink (agents shouldn't write deps anyway — correct).
 - The `.vinta-ai-workflows/` dir (summary YAMLs, prs-context) is shared/symlinked but **written** during a run, so it must be passed as an `--allow` path (or made a real writable dir in the worktree). Record which.
 
+### 5.5a — In-process runtimes (claude-code)
+
+`sandbox-run.sh` confines a **process**: it wraps the command that launches a subagent. That only works when the runtime spawns subagents as **subprocesses** (`codex exec …`, a `claude -p …` child, a custom runner) — you wrap that argv and the kernel blocks the child's main-checkout writes.
+
+**Claude Code runs subagents in-process.** Its Task tool shares the orchestrator's OS process and tool pipeline — there's no child launch command to wrap. The guard has to live in the harness's own config instead. Two complementary layers, both bundled here, both matching the same deny-main/allow-rest model:
+
+- **Layer A — `PreToolUse` write-guard hook** ([scripts/claude-worktree-write-guard.py](scripts/claude-worktree-write-guard.py)). A session-level `PreToolUse` hook fires for **every** tool call in the session — orchestrator **and** every in-process Task subagent — because they run through the same pipeline. This hook matches the file-editing tools (`Edit|Write|MultiEdit|NotebookEdit`), realpath-resolves the target, and blocks (exit 2 → the model gets the reason and retries) any write that escapes the worktree into the main checkout. Filesystem-only, **no network impact**. This is the load-bearing claude-code guard and the concrete form of implement-plan's "runtime pre-write guard hook" option.
+
+- **Layer B — Claude Code's native OS sandbox** (opt-in). Claude Code has adopted the same OS model `sandbox-run.sh` implements (`sandbox-exec` / `bwrap`), configured via `sandbox.filesystem.denyWrite` / `allowWrite` in `settings.json` instead of a wrapper, and it applies to **Bash run inside subagents** too. Turning it on closes the one gap Layer A leaves — a write issued through **Bash** (`echo > <main>/f`), which a file-tool hook can't see. **Caveat: enabling the native sandbox also turns on network isolation**, so `pnpm install` / `git push` break unless you allow-list the registry + git-remote hosts. Without Layer B, Bash-issued stray writes fall back to implement-plan's post-run `git -C <main> status` backstop (Layer 1).
+
+Generate both with [scripts/gen-claude-sandbox-settings.sh](scripts/gen-claude-sandbox-settings.sh):
+
+```bash
+# Layer A only (filesystem-only, no network config needed):
+scripts/gen-claude-sandbox-settings.sh --worktree <worktree-path> --main <main-checkout-root>
+
+# Layer A + B (also OS-block Bash writes; must allow-list network hosts):
+scripts/gen-claude-sandbox-settings.sh --worktree <worktree-path> --main <main-checkout-root> \
+  --os-sandbox --allow-domain <registry-host> --allow-domain <git-remote-host>
+```
+
+It writes `<worktree>/.claude/settings.json` (merging, not clobbering) with `<worktree>`, `<main>/.git` (git worktrees commit into the main repo's `.git` — **must** stay writable), and `.vinta-ai-workflows` punched back to writable.
+
+**Two deployment models — settings are read at session start:**
+
+1. **Worktree-rooted session (recommended).** Run the plan from inside the worktree (`cd <worktree> && claude`). The generated `<worktree>/.claude/settings.json` governs that session and all its Task subagents. As a bonus, claude-code's default working-directory boundary already discourages file writes above cwd, so this is belt-and-suspenders. Provision the worktree + settings **before** starting the plan session.
+2. **Config in the invocation's project root.** If the orchestrator already runs in the main checkout (implement-plan's default topology), the hook + sandbox must instead live in the main checkout's `settings.json` / `settings.local.json` **before** that session starts — the native `sandbox` block in particular is read at launch and won't retroactively cage an already-running session. Provision first, then start the plan; don't expect a mid-run `use_worktree` opt-in to enable the OS sandbox for the session that requested it.
+
+Record the achieved tier the same way as the subprocess path: `enforced` when Layer B is active (or Layer A alone if the team accepts hook-only), `none` when neither is wired.
+
 ## Step 6 — Write the summary file
 
 `.vinta-ai-workflows/worktrees/<name>.yaml` (committed to `.gitignore` via the existing `.vinta-ai-workflows/` umbrella). Schema:
@@ -279,9 +309,13 @@ state:
     cron_disabled: <bool>
   sandbox:
     tier: enforced | none          # from the Filesystem sandbox step's capability probe
-    launcher: sandbox-exec | bwrap | null   # null when tier=none
+    launcher: sandbox-exec | bwrap | claude-hook | claude-native-sandbox | null
+    # sandbox-exec / bwrap        → subprocess runtimes via scripts/sandbox-run.sh
+    # claude-hook                 → in-process (claude-code) Layer A hook only (file tools)
+    # claude-native-sandbox       → in-process (claude-code) Layer A hook + Layer B OS sandbox
+    # null                        → tier=none (no guard wired)
     deny: [<main-checkout-root>]   # subtree(s) made read-only inside the cage
-    allow: [<worktree-path>, <.vinta-ai-workflows-dir>]   # writable exceptions
+    allow: [<worktree-path>, <main-checkout-root>/.git, <.vinta-ai-workflows-dir>]  # writable exceptions
 notes: |
   <freeform — anything the user / agent should know>
 ```
@@ -349,7 +383,8 @@ Every step gated on user confirmation when the worktree has un-pushed branches.
 - **Every fork decision lands in `.vinta-ai-workflows/worktrees/<name>.yaml`.** Teardown reads it; humans grep it; agents resuming a stalled plan read it. No decision lives only in conversation memory.
 - **Worktree root governed by runtime conventions.** claude-code uses `.claude/worktrees/`; other harnesses use sibling dirs. Don't fight the harness — match it.
 - **Don't mutate the main checkout from this skill.** Every write goes to the worktree or to `.vinta-ai-workflows/`. Forking a Postgres DB is the one exception (the new DB lives in the same server) — document it loudly in the summary.
-- **Sandbox is the deterministic guard; the prompt is not.** When a sandbox tool exists, the [Filesystem sandbox](#step-55--filesystem-sandbox-os-level-write-guard) step's `sandbox-run.sh` makes the main checkout read-only for any spawned command — this is what actually *prevents* stray main-checkout writes across harnesses. Telling the agent "stay in the worktree" is best-effort only. Always probe + record the tier; never claim prevention when `tier=none`.
+- **Sandbox is the deterministic guard; the prompt is not.** When a sandbox tool exists, the [Filesystem sandbox](#step-55--filesystem-sandbox-os-level-write-guard) step's `sandbox-run.sh` makes the main checkout read-only for any spawned command — this is what actually *prevents* stray main-checkout writes for subprocess runtimes. For **in-process** runtimes (claude-code's Task tool) there's no subprocess to wrap: wire the `PreToolUse` hook (+ optional native OS sandbox) from [In-process runtimes (claude-code)](#55a--in-process-runtimes-claude-code) into the session's `settings.json` instead. Telling the agent "stay in the worktree" is best-effort only either way. Always probe + record the tier; never claim prevention when `tier=none`.
+- **`<main>/.git` stays writable in every model.** Git worktrees store their commits in the main repo's `.git`; a deny that also blocks `<main>/.git` breaks every commit made inside the worktree. `sandbox-run.sh` callers and the generated claude-code settings must both `--allow` / `allowWrite` `<main>/.git`.
 - **Deny-main, allow-rest — never allow-worktree-only.** Locking everything except the worktree breaks package managers / caches / `$HOME`. Lock only the main checkout subtree; re-allow the worktree (nested under it) and the written `.vinta-ai-workflows` dir. Don't tighten further without testing the project's real lint / test / build / migrate commands inside the cage.
 - **Worktree base = `origin/<default-branch>` by default.** `HEAD` only when the user explicitly confirms; record the choice in the summary.
 - **Refuse to provision a second worktree for the same branch.** Git enforces this — don't try to work around it.

package/skills/vinta-derive-skills/resources/foundation-skills/prepare-worktree/scripts/claude-worktree-write-guard.py

@@ -0,0 +1,118 @@
+#!/usr/bin/env python3
+"""claude-worktree-write-guard.py — Claude Code PreToolUse hook that blocks
+file-tool writes escaping a worktree into the protected main checkout.
+
+Why this exists: Claude Code runs sub-agents (the Task tool) IN-PROCESS — they
+share the orchestrator's OS process and tool pipeline, so there is no child
+launch command to wrap with an OS sandbox (that model only works on harnesses
+that spawn sub-agents as subprocesses, e.g. `codex exec`). A session-level
+PreToolUse hook, by contrast, fires for every tool call in the session —
+orchestrator AND Task sub-agents alike — because they run through the same
+pipeline. This hook is the in-process equivalent of prepare-worktree's
+`sandbox-run.sh` deny-main/allow-rest guard, scoped to the file-editing tools.
+
+Scope: the file-write tools only — Edit, Write, MultiEdit, NotebookEdit. Bash
+writes are NOT covered here (a hook can't reliably know every path a shell
+command touches); use Claude Code's native `sandbox` (see
+gen-claude-sandbox-settings.sh `--os-sandbox`) for OS-level Bash confinement,
+and rely on implement-plan's post-run `git -C <main> status` backstop otherwise.
+
+Model — deny-main, allow-rest (mirrors sandbox-run.sh): every path is allowed
+EXCEPT ones that resolve under a --deny root, and an --allow root punches a
+subtree back to writable even when nested under a --deny root. The worktree
+usually lives UNDER the main checkout (.claude/worktrees/<name>/), and git
+worktrees write commits into <main>/.git, so both the worktree and <main>/.git
+are passed as --allow. Symlinks are resolved (realpath) before the check, so a
+write through a symlink that lands back in the main checkout (e.g. a shared
+node_modules) is correctly caught.
+
+Usage (wired by gen-claude-sandbox-settings.sh into settings.json hooks):
+    claude-worktree-write-guard.py \
+        --deny  <main-checkout-root> \
+        --allow <worktree-path> \
+        --allow <main-checkout-root>/.git \
+        --allow <main-checkout-root>/.vinta-ai-workflows
+
+Reads the PreToolUse event JSON on stdin. Blocks by exiting 2 with a reason on
+stderr — Claude Code feeds that stderr back to the model as the denial reason,
+so the agent retries against the correct worktree path. Any non-write tool, or
+a write that stays inside an --allow subtree, exits 0 (allowed). The guard fails
+OPEN (exit 0) on malformed input or its own errors — it is a safety net layered
+under the OS sandbox and the post-run backstop, never the sole gate, and must
+never wedge a run by denying on a parsing hiccup.
+"""
+import json
+import os
+import sys
+
+# Tool-input keys that carry a write target, per tool.
+PATH_KEYS = ("file_path", "notebook_path")
+GUARDED_TOOLS = {"Edit", "Write", "MultiEdit", "NotebookEdit"}
+
+
+def canon(path):
+    """Absolute, symlink-resolved path. realpath resolves a shared node_modules
+    / .vinta-ai-workflows symlink back to its real location so the prefix check
+    reflects where the byte actually lands, not the symlink's apparent path."""
+    return os.path.realpath(os.path.abspath(path))
+
+
+def under(path, root):
+    """True if `path` is `root` or nested beneath it. Compares canonical paths
+    with a trailing separator so /main-evil is not treated as under /main."""
+    path, root = canon(path), canon(root)
+    return path == root or path.startswith(root.rstrip(os.sep) + os.sep)
+
+
+def parse_args(argv):
+    deny, allow = [], []
+    i = 0
+    while i < len(argv):
+        if argv[i] == "--deny" and i + 1 < len(argv):
+            deny.append(argv[i + 1]); i += 2
+        elif argv[i] == "--allow" and i + 1 < len(argv):
+            allow.append(argv[i + 1]); i += 2
+        else:
+            i += 1
+    return deny, allow
+
+
+def main():
+    deny, allow = parse_args(sys.argv[1:])
+    if not deny:
+        # Nothing to protect — nothing to do.
+        return 0
+
+    try:
+        event = json.load(sys.stdin)
+    except Exception:
+        return 0  # fail open — never wedge a run on a parse error
+
+    if event.get("tool_name") not in GUARDED_TOOLS:
+        return 0
+
+    tool_input = event.get("tool_input") or {}
+    target = next((tool_input[k] for k in PATH_KEYS if tool_input.get(k)), None)
+    if not target:
+        return 0  # no write target we recognize
+
+    # allow wins over deny (the worktree + .git + .vinta-ai-workflows are nested
+    # under the denied main root and must stay writable).
+    if any(under(target, a) for a in allow):
+        return 0
+    if any(under(target, d) for d in deny):
+        resolved = canon(target)
+        wt = allow[0] if allow else "the worktree"
+        sys.stderr.write(
+            f"Blocked write to the main checkout: {resolved}\n"
+            f"This file is outside the worktree. Write to the worktree instead "
+            f"(under {wt}). If you meant to edit a shared file, it is protected "
+            f"for the duration of this plan run.\n"
+        )
+        return 2  # exit 2 → Claude Code blocks the call, stderr is the reason
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/vinta-derive-skills/resources/foundation-skills/prepare-worktree/scripts/gen-claude-sandbox-settings.sh

@@ -0,0 +1,167 @@
+#!/usr/bin/env bash
+# gen-claude-sandbox-settings.sh — generate a Claude Code settings.json that
+# confines a worktree session (orchestrator + its in-process Task sub-agents)
+# to writing inside the worktree, blocking stray writes to the main checkout.
+#
+# Claude Code runs sub-agents in-process (the Task tool shares the orchestrator's
+# OS process), so the subprocess-wrapping model of sandbox-run.sh does not apply
+# — the guard has to live in the harness's own settings. This script wires two
+# complementary layers, matching prepare-worktree's deny-main/allow-rest model:
+#
+#   Layer A (always) — a PreToolUse hook (claude-worktree-write-guard.py) that
+#     blocks the file-editing tools (Edit/Write/MultiEdit/NotebookEdit) from
+#     writing outside the worktree. Filesystem-only; no network impact. Fires
+#     for the orchestrator AND every Task sub-agent (shared session pipeline).
+#
+#   Layer B (opt-in, --os-sandbox) — Claude Code's NATIVE OS sandbox
+#     (`sandbox.filesystem.denyWrite`/`allowWrite`, Seatbelt on macOS / bwrap on
+#     Linux) so Bash-issued writes are blocked at the kernel too. NOTE: enabling
+#     the native sandbox also turns on NETWORK isolation — dep installs and
+#     `git push` break unless you allow-list registries/remotes. Pass the hosts
+#     the plan needs via --allow-domain (repeatable). Without --os-sandbox, Bash
+#     writes fall back to implement-plan's post-run `git -C <main> status` check.
+#
+# Both layers keep <worktree>, <main>/.git (git worktrees commit into the main
+# repo's .git), and the shared .vinta-ai-workflows dir writable.
+#
+# Usage:
+#   gen-claude-sandbox-settings.sh \
+#     --worktree <worktree-path> \
+#     --main     <main-checkout-root> \
+#     [--allow <extra-writable-path>]...   # e.g. .vinta-ai-workflows if elsewhere
+#     [--out <settings-file>]              # default: <worktree>/.claude/settings.json
+#     [--os-sandbox]                       # also emit the native sandbox block
+#     [--allow-domain <host>]...           # network hosts to allow under --os-sandbox
+#
+# The generated file is meant to govern a Claude Code session ROOTED IN THE
+# WORKTREE (`cd <worktree> && claude`), the recommended claude-code topology for
+# an isolated plan run — the settings are read at session start. See Step 5.5 of
+# ../SKILL.md for the two deployment models and their timing caveats.
+#
+# Exit: 0 on success; 2 on argument/setup errors.
+
+set -u
+
+die() { echo "gen-claude-sandbox-settings: $*" >&2; exit 2; }
+
+SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)
+GUARD="$SCRIPT_DIR/claude-worktree-write-guard.py"
+
+WORKTREE=""; MAIN=""; OUT=""; OS_SANDBOX=0
+EXTRA_ALLOW=(); DOMAINS=()
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --worktree)     shift; [ $# -gt 0 ] || die "--worktree needs a path"; WORKTREE="$1"; shift ;;
+    --main)         shift; [ $# -gt 0 ] || die "--main needs a path"; MAIN="$1"; shift ;;
+    --out)          shift; [ $# -gt 0 ] || die "--out needs a path"; OUT="$1"; shift ;;
+    --allow)        shift; [ $# -gt 0 ] || die "--allow needs a path"; EXTRA_ALLOW+=("$1"); shift ;;
+    --allow-domain) shift; [ $# -gt 0 ] || die "--allow-domain needs a host"; DOMAINS+=("$1"); shift ;;
+    --os-sandbox)   OS_SANDBOX=1; shift ;;
+    *)              die "unknown arg: $1" ;;
+  esac
+done
+
+[ -n "$WORKTREE" ] || die "--worktree <path> required"
+[ -n "$MAIN" ]     || die "--main <path> required"
+[ -f "$GUARD" ]    || die "guard hook not found next to this script: $GUARD"
+
+# Canonicalize (leaf need not exist).
+canon() {
+  local p="$1" d b
+  if [ -d "$p" ]; then (cd "$p" && pwd -P); return; fi
+  d=$(dirname "$p"); b=$(basename "$p")
+  if [ -d "$d" ]; then echo "$(cd "$d" && pwd -P)/$b"; else echo "$p"; fi
+}
+
+WORKTREE=$(canon "$WORKTREE")
+MAIN=$(canon "$MAIN")
+[ -d "$WORKTREE" ] || die "worktree path is not a directory: $WORKTREE"
+[ -d "$MAIN" ]     || die "main checkout path is not a directory: $MAIN"
+[ -z "$OUT" ] && OUT="$WORKTREE/.claude/settings.json"
+
+# Writable exceptions punched back through the main-checkout deny: the worktree,
+# the shared git database (worktree commits land in <main>/.git), the shared
+# .vinta-ai-workflows dir, plus any caller extras.
+ALLOW=("$WORKTREE" "$MAIN/.git" "$MAIN/.vinta-ai-workflows")
+for p in "${EXTRA_ALLOW[@]:-}"; do [ -n "$p" ] && ALLOW+=("$(canon "$p")"); done
+
+if [ "$OS_SANDBOX" -eq 1 ] && [ "${#DOMAINS[@]}" -eq 0 ]; then
+  echo "gen-claude-sandbox-settings: WARNING --os-sandbox with no --allow-domain — network" >&2
+  echo "  isolation is ON, so dep installs / git push over the network will fail. Pass the" >&2
+  echo "  registry + git remote hosts via --allow-domain, or drop --os-sandbox for hook-only." >&2
+fi
+
+mkdir -p "$(dirname "$OUT")" || die "cannot create settings dir for $OUT"
+
+# Emit JSON via python3 (safe escaping of paths); merge into an existing file if
+# one is present so we don't clobber unrelated settings the worktree may carry.
+GUARD="$GUARD" OUT="$OUT" MAIN="$MAIN" WORKTREE="$WORKTREE" OS_SANDBOX="$OS_SANDBOX" \
+python3 - "${ALLOW[@]}" -- "${DOMAINS[@]:-}" <<'PY' || die "failed to write settings"
+import json, os, sys
+
+guard, out, main, worktree = (os.environ[k] for k in ("GUARD", "OUT", "MAIN", "WORKTREE"))
+os_sandbox = os.environ["OS_SANDBOX"] == "1"
+
+sep = sys.argv.index("--")
+allow = [a for a in sys.argv[1:sep] if a]
+domains = [d for d in sys.argv[sep + 1:] if d]
+
+# Layer A — PreToolUse write-guard hook (always).
+guard_cmd = " ".join(
+    [json.dumps(guard) if " " in guard else guard, "--deny", main]
+    + sum((["--allow", a] for a in allow), [])
+)
+hook_entry = {
+    "matcher": "Edit|Write|MultiEdit|NotebookEdit",
+    "hooks": [{"type": "command", "command": guard_cmd}],
+}
+
+# Merge into an existing settings file if present (preserve unrelated keys).
+settings = {}
+if os.path.exists(out):
+    try:
+        with open(out) as f:
+            settings = json.load(f) or {}
+    except Exception:
+        settings = {}
+
+hooks = settings.setdefault("hooks", {})
+pre = hooks.setdefault("PreToolUse", [])
+# Drop any prior guard entry (idempotent re-runs) then append the fresh one.
+pre = [e for e in pre if "claude-worktree-write-guard" not in json.dumps(e)]
+pre.append(hook_entry)
+hooks["PreToolUse"] = pre
+
+# Layer B — native OS sandbox (opt-in).
+if os_sandbox:
+    settings["sandbox"] = {
+        "enabled": True,
+        # Degrade to unsandboxed on platforms without Seatbelt/bwrap rather than
+        # hard-failing the run; the hook (Layer A) still guards file writes.
+        "failIfUnavailable": False,
+        "filesystem": {
+            "denyWrite": [main],
+            "allowWrite": allow,
+        },
+        "network": {
+            # Sandbox forces network isolation; without an allow-list, installs
+            # and pushes break. Callers pass registry + remote hosts.
+            "allowedDomains": domains,
+        },
+    }
+
+with open(out, "w") as f:
+    json.dump(settings, f, indent=2)
+    f.write("\n")
+
+print(f"wrote {out}")
+print(f"  layer A (hook): guard on Edit|Write|MultiEdit|NotebookEdit, deny {main}")
+print(f"  allow-write: {', '.join(allow)}")
+if os_sandbox:
+    dom = ", ".join(domains) if domains else "(none — network will be blocked)"
+    print(f"  layer B (os sandbox): enabled, network allowedDomains: {dom}")
+else:
+    print("  layer B (os sandbox): OFF (hook-only; Bash writes rely on the post-run backstop)")
+PY
+
+echo "gen-claude-sandbox-settings: done."

package/skills/vinta-derive-skills/resources/foundation-skills/prepare-worktree/scripts/sandbox-run.sh

@@ -75,7 +75,9 @@ fi
 
 # ---- macOS: sandbox-exec -----------------------------------------------------
 if command -v sandbox-exec >/dev/null 2>&1; then
-  profile=$(mktemp -t vinta-sandbox) || die "mktemp failed"
+  # Explicit XXXXXX template (portable across BSD mktemp on stock macOS and GNU
+  # mktemp from coreutils — `mktemp -t prefix` is not portable between them).
+  profile=$(mktemp "${TMPDIR:-/tmp}/vinta-sandbox.XXXXXX") || die "mktemp failed"
   trap 'rm -f "$profile"' EXIT
   {
     echo '(version 1)'