@erclx/aitk 0.19.0 → 0.20.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "aitk",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/scripts/lib/sandbox-path.sh

@@ -0,0 +1,108 @@
+#!/usr/bin/env bash
+
+# The sandbox tree lives outside the toolkit worktree. `scripts/sandbox/run.sh`
+# sets cwd to it for `claude -p`, and every `CLAUDE.md` between that cwd and the
+# filesystem root loads into the session. Under the repository the toolkit's own
+# instructions join that chain beside the seeded copy the scenario installed,
+# both carry the rule sending shared session scratch to the main worktree root,
+# and nothing decides which root wins. A session picking the toolkit writes its
+# output where no manifest reads it, so the run reports success while the verdict
+# reports no writes at all. `scripts/eval/run.sh` keeps its fixture outside the
+# repository for the same reason.
+#
+# Twin of `SANDBOX_DIR` in `src/commands/sandbox.ts`. The exec boundary rules out
+# a shared constant, so a change to the default lands on both sides.
+resolve_sandbox_dir() {
+  if [ -n "${AITK_SANDBOX_DIR:-}" ]; then
+    printf '%s\n' "$AITK_SANDBOX_DIR"
+    return 0
+  fi
+
+  printf '%s/aitk/sandbox\n' "${XDG_STATE_HOME:-$HOME/.local/state}"
+}
+
+# Collapses repeated separators and strips every trailing one, leaving a bare
+# root as `/`. Every comparison below is a string test, so `//` and `$HOME//`
+# would otherwise read as paths no rule names.
+normalize_sandbox_path() {
+  local path="$1"
+
+  while [ "$path" != "${path//\/\//\/}" ]; do
+    path="${path//\/\//\/}"
+  done
+
+  while [ "${#path}" -gt 1 ] && [ "${path%/}" != "$path" ]; do
+    path="${path%/}"
+  done
+
+  printf '%s' "$path"
+}
+
+# Whether `candidate` is `target` or a directory containing it. Removing the
+# former removes the latter, which is what makes an ancestor as dangerous as an
+# exact match.
+is_at_or_above() {
+  local candidate="$1"
+  local target="$2"
+
+  [ "$candidate" = "$target" ] || [ "${target#"$candidate"/}" != "$target" ]
+}
+
+# Prints the reason a location is unusable and returns non-zero, so the caller
+# reports one message naming the path rather than a bare refusal.
+#
+# Provisioning runs `rm -rf` on this path at three sites before staging, so the
+# test is an allowlist rather than a list of paths to refuse. A blocklist has to
+# name every system directory to be right once and stays wrong as soon as one is
+# missed, while requiring a strict descendant of the home directory or of the
+# temp root admits the default and every reasonable override and refuses `/`,
+# `/usr`, `/etc`, and `$HOME` itself without naming any of them.
+#
+# The repository test is separate and runs both ways. A path under the worktree
+# restores the ancestor chain the relocation removed, and a path above it is one
+# `rm -rf` away from deleting the repository. It resolves the main worktree root
+# rather than trusting `$PROJECT_ROOT`, since a linked worktree is itself inside
+# that root.
+assert_sandbox_dir_safe() {
+  local raw="$1"
+  local root="${2:-${PROJECT_ROOT:-$PWD}}"
+
+  if [ -z "$raw" ] || [ "${raw#/}" = "$raw" ]; then
+    printf 'AITK_SANDBOX_DIR must be an absolute path, got: %s\n' "${raw:-<empty>}"
+    return 1
+  fi
+
+  local dir home temp
+  dir="$(normalize_sandbox_path "$raw")"
+  home="$(normalize_sandbox_path "${HOME:-/root}")"
+  temp="$(normalize_sandbox_path "${TMPDIR:-/tmp}")"
+
+  if ! is_at_or_above "$home" "$dir" && ! is_at_or_above "$temp" "$dir"; then
+    printf 'Refusing %s as the sandbox. Provisioning removes the tree first, so the path has to sit under %s or %s.\n' "$raw" "$home" "$temp"
+    return 1
+  fi
+
+  if [ "$dir" = "$home" ] || [ "$dir" = "$temp" ]; then
+    printf 'Refusing %s as the sandbox. Provisioning removes the tree first, so the path has to sit under %s rather than be it.\n' "$raw" "$dir"
+    return 1
+  fi
+
+  local main_root
+  main_root="$(git -C "$root" worktree list --porcelain 2>/dev/null |
+    grep -m 1 '^worktree ' | cut -d' ' -f2-)"
+  main_root="$(normalize_sandbox_path "${main_root:-$root}")"
+
+  if is_at_or_above "$dir" "$main_root"; then
+    printf 'Refusing %s as the sandbox. Provisioning removes the tree first, and that path contains %s.\n' "$raw" "$main_root"
+    return 1
+  fi
+
+  case "$dir" in
+  "$main_root"/*)
+    printf 'Sandbox at %s sits inside %s, which puts the toolkit CLAUDE.md back on the session ancestor chain. Point AITK_SANDBOX_DIR outside the repository.\n' "$raw" "$main_root"
+    return 1
+    ;;
+  esac
+
+  return 0
+}

package/scripts/lib/ui.sh

@@ -6,6 +6,12 @@ if [ "${BASH_VERSINFO[0]:-0}" -lt 4 ]; then
   exit 1
 fi
 
+# Resolved from this file's own location rather than `$PROJECT_ROOT`, because
+# `require_project_root` is what several scripts call before anything has
+# established a root.
+# shellcheck source=/dev/null
+source "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")/sandbox-path.sh"
+
 GREEN='\033[0;32m'
 RED='\033[0;31m'
 YELLOW='\033[0;33m'
@@ -46,7 +52,9 @@ guard_root() {
 }
 
 require_project_root() {
-  if [[ "$PWD" == *".sandbox"* ]]; then
+  local sandbox
+  sandbox="$(resolve_sandbox_dir)"
+  if [[ "$PWD" == "$sandbox" || "$PWD" == "$sandbox"/* ]]; then
     echo -e "${GREY}┌${NC}" >&2
     log_error "Execution restricted: Command cannot be run from inside the sandbox environment."
   fi

package/scripts/manage-sandbox.sh

@@ -8,6 +8,7 @@ export PROJECT_ROOT
 
 source "$PROJECT_ROOT/scripts/config.sh"
 source "$PROJECT_ROOT/scripts/lib/ui.sh"
+source "$PROJECT_ROOT/scripts/lib/sandbox-path.sh"
 source "$PROJECT_ROOT/scripts/lib/sandbox-git.sh"
 source "$PROJECT_ROOT/scripts/lib/sandbox-fixtures.sh"
 
@@ -135,8 +136,8 @@ validate_environment() {
     log_error "Sandbox directory not found at: $SANDBOX_DIR"
   fi
 
-  if [[ "$PWD" == *".sandbox"* ]]; then
-    log_warn "Detected execution inside .sandbox. Switching to project root..."
+  if [[ "$PWD" == "$SANDBOX" || "$PWD" == "$SANDBOX"/* ]]; then
+    log_warn "Detected execution inside the sandbox. Switching to project root..."
     cd "$PROJECT_ROOT" || log_error "Failed to switch to project root."
   fi
 }
@@ -324,7 +325,7 @@ finalize_sandbox_run() {
 cmd_clean() {
   log_step "Removing sandbox"
   rm -rf "$SANDBOX"
-  log_rem ".sandbox/"
+  log_rem "$SANDBOX"
   trap - EXIT
   close_timeline
   echo "" >&2
@@ -422,9 +423,14 @@ main() {
     log_error "Context error: you must run this command from inside the toolkit repository."
   fi
 
-  SANDBOX="$PROJECT_ROOT/.sandbox"
+  SANDBOX="$(resolve_sandbox_dir)"
   SANDBOX_DIR="$PROJECT_ROOT/scripts/sandbox"
 
+  local unsafe
+  if ! unsafe="$(assert_sandbox_dir_safe "$SANDBOX" "$PROJECT_ROOT")"; then
+    log_error "$unsafe"
+  fi
+
   if [[ "$1" == "reset" ]]; then
     reset_sandbox
     exit 0

package/src/commands/sandbox.ts

@@ -1,4 +1,5 @@
 import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { homedir } from 'node:os'
 import { join } from 'node:path'
 import type { Command } from 'commander'
 import { PROJECT_ROOT, execScript } from '@/exec'
@@ -28,6 +29,29 @@ import {
 
 const SANDBOX_DIR = join(PROJECT_ROOT, 'scripts', 'sandbox')
 
+/**
+ * The provisioned tree, as opposed to `SANDBOX_DIR` above, which holds the
+ * scenario scripts. It sits outside the toolkit worktree so the toolkit's own
+ * `CLAUDE.md` stays off the ancestor chain of the session `run.sh` spawns with
+ * cwd here.
+ *
+ * Twin of `resolve_sandbox_dir` in `scripts/lib/sandbox-path.sh`. The exec
+ * boundary rules out a shared constant, so a change to the default lands on both
+ * sides.
+ */
+function sandboxTree(): string {
+  const override = process.env.AITK_SANDBOX_DIR
+  if (override !== undefined && override !== '') return override
+
+  const state = process.env.XDG_STATE_HOME
+  const base =
+    state !== undefined && state !== ''
+      ? state
+      : join(homedir(), '.local', 'state')
+
+  return join(base, 'aitk', 'sandbox')
+}
+
 /**
  * Holds fixture content for scenarios rather than scenarios of its own.
  * Twin of the `-not -name fixtures` filter in `scripts/manage-sandbox.sh`.
@@ -224,7 +248,7 @@ function runCheck(
   // A sandbox that was never provisioned fails every path assertion, reading as a
   // skill that did nothing rather than a caller that ran check too early. The
   // whole point of a verdict is that it means what it says.
-  const sandboxDir = join(PROJECT_ROOT, '.sandbox')
+  const sandboxDir = sandboxTree()
   if (!existsSync(sandboxDir)) {
     logError(`No sandbox at ${sandboxDir}. Provision one with aitk sandbox.`)
     outro()

package/src/sandbox/expect.ts

@@ -141,9 +141,33 @@ function contentArray(value: unknown): ContentAssertion[] {
     if (typeof entry !== 'object' || entry === null) continue
 
     const record = entry as Record<string, unknown>
+
+    // Dropping a half-written entry rather than throwing is deliberate, and it
+    // reads as the opposite of the stray-key check below. An entry missing its
+    // path or pattern declares no assertion to lose, and `checkExpectation`
+    // fails an arm whose surviving declaration asserts nothing, so the vacuous
+    // pass is already closed one level up. A stray key is the reverse: the entry
+    // is well-formed and the declaration around it silently lost a key it
+    // appears to carry, which nothing downstream can see.
     if (typeof record.path !== 'string' || record.path === '') continue
     if (typeof record.pattern !== 'string' || record.pattern === '') continue
 
+    // A bare key written below a `[[content]]` header belongs to that table in
+    // TOML, not to the document, so a declaration listing `manual` or
+    // `max_turns` after its content blocks parses clean and silently asserts
+    // neither. The `claude/ui-test` arm shipped that way: a turn ceiling that
+    // never ran and five manual entries that never reached the unchecked count,
+    // while `aitk sandbox coverage` counted the arm as armed. Nothing at the
+    // top level can see the difference, so the check belongs here.
+    const stray = Object.keys(record).filter(
+      (key) => key !== 'path' && key !== 'pattern',
+    )
+    if (stray.length > 0) {
+      throw new Error(
+        `content entry for ${record.path} carries ${stray.join(', ')}. Move top-level keys above the first [[content]] block.`,
+      )
+    }
+
     assertions.push({ path: record.path, pattern: record.pattern })
   }
 
@@ -257,6 +281,20 @@ function checkWriteScope(
     }
   }
 
+  // A scope produces one result per write, so a run that wrote nothing produces
+  // none, and without this the declaration vanishes from the verdict entirely:
+  // no result, no skipped entry, and no contribution to the unchecked count that
+  // exists to surface exactly this. The `undefined` branch above cannot stand in,
+  // since `run.sh` always passes `--writes` and `readWrites` returns `[]` for an
+  // empty file. An arm whose output escaped the snapshot reads as a clean run,
+  // which is the vacuous pass the harness exists to remove.
+  if (writes.length === 0) {
+    return {
+      results: [],
+      skipped: ['write scope: the run wrote nothing, so no path was checked'],
+    }
+  }
+
   const globs = expectation.writeScope.map((glob) => new Bun.Glob(glob))
 
   return {