@imdeadpool/guardex 7.0.16 → 7.0.18

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@imdeadpool/guardex",
-  "version": "7.0.16",
-  "description": "GitGuardex: hardened multi-agent git guardrails for parallel agent work.",
+  "version": "7.0.18",
+  "description": "Guardian T-Rex for your multi-agent repo. Isolated worktrees, file locks, and PR-only merges stop parallel Codex & Claude agents from overwriting each other's work. Auto-wires Oh My Codex, Oh My Claude, OpenSpec, and Caveman.",
   "license": "MIT",
   "preferGlobal": true,
   "bin": {

package/templates/AGENTS.multiagent-safety.md

@@ -7,22 +7,22 @@
 `GUARDEX_ON=0` disables Guardex for that repo.
 `GUARDEX_ON=1` explicitly enables Guardex for that repo again.
 
-**Isolation.** Every task runs on a dedicated `agent/*` branch + worktree. Start with `scripts/agent-branch-start.sh "<task>" "<agent-name>"`. Treat the base branch (`main`/`dev`) as read-only while an agent branch is active. Never `git checkout <branch>` on a primary working tree (including nested repos); use `git worktree add` instead. The `.githooks/post-checkout` hook auto-reverts primary-branch switches during agent sessions - bypass only with `GUARDEX_ALLOW_PRIMARY_BRANCH_SWITCH=1`.
+**Isolation.** Every task runs on a dedicated `agent/*` branch + worktree. Start with `gx branch start "<task>" "<agent-name>"`. Treat the base branch (`main`/`dev`) as read-only while an agent branch is active. Never `git checkout <branch>` on a primary working tree (including nested repos); use `git worktree add` instead. The `.githooks/post-checkout` hook auto-reverts primary-branch switches during agent sessions - bypass only with `GUARDEX_ALLOW_PRIMARY_BRANCH_SWITCH=1`.
 For every new task, including follow-up work in the same chat/session, if an assigned agent sub-branch/worktree is already open, continue in that sub-branch instead of creating a fresh lane unless the user explicitly redirects scope.
 Never implement directly on the local/base branch checkout; keep it unchanged and perform all edits in the agent sub-branch/worktree.
 
-**Ownership.** Before editing, claim files: `scripts/agent-file-locks.py claim --branch "<agent-branch>" <file...>`. Before deleting, confirm the path is in your claim. Don't edit outside your scope unless reassigned.
+**Ownership.** Before editing, claim files: `gx locks claim --branch "<agent-branch>" <file...>`. Before deleting, confirm the path is in your claim. Don't edit outside your scope unless reassigned.
 
 **Handoff gate.** Post a one-line handoff note (plan/change, owned scope, intended action) before editing. Re-read the latest handoffs before replacing others' code.
 
-**Completion.** Finish with `scripts/agent-branch-finish.sh --branch "<agent-branch>" --via-pr --wait-for-merge --cleanup` (or `gx finish --all`). Task is only complete when: commit pushed, PR URL recorded, state = `MERGED`, sandbox worktree pruned. If anything blocks, append a `BLOCKED:` note and stop - don't half-finish.
+**Completion.** Finish with `gx branch finish --branch "<agent-branch>" --via-pr --wait-for-merge --cleanup` (or `gx finish --all`). Task is only complete when: commit pushed, PR URL recorded, state = `MERGED`, sandbox worktree pruned. If anything blocks, append a `BLOCKED:` note and stop - don't half-finish.
 OMX completion policy: when a task is done, the agent must commit the task changes, push the agent branch, and create/update a PR before considering the branch complete.
 
 **Parallel safety.** Assume other agents edit nearby. Never revert unrelated changes. Report conflicts in the handoff.
 
 **Reporting.** Every completion handoff includes: files changed, behavior touched, verification commands + results, risks/follow-ups.
 
-**OpenSpec (when change-driven).** Keep `openspec/changes/<slug>/tasks.md` checkboxes current during work, not batched at the end. Task scaffolds and manual task edits must include an explicit final completion/cleanup section that ends with PR merge + sandbox cleanup (`gx finish --via-pr --wait-for-merge --cleanup` or `scripts/agent-branch-finish.sh ... --cleanup`) and records PR URL + final `MERGED` evidence. Verify specs with `openspec validate --specs` before archive. Don't archive unverified.
+**OpenSpec (when change-driven).** Keep `openspec/changes/<slug>/tasks.md` checkboxes current during work, not batched at the end. Task scaffolds and manual task edits must include an explicit final completion/cleanup section that ends with PR merge + sandbox cleanup (`gx finish --via-pr --wait-for-merge --cleanup` or `gx branch finish ... --cleanup`) and records PR URL + final `MERGED` evidence. Verify specs with `openspec validate --specs` before archive. Don't archive unverified.
 
 **Version bumps.** If a change bumps a published version, the same PR updates release notes/changelog.
 <!-- multiagent-safety:END -->

package/templates/githooks/post-checkout

@@ -64,7 +64,7 @@ echo "[agent-primary-branch-guard] Primary checkout switched branches." >&2
 echo "[agent-primary-branch-guard]   from: $prev_branch (protected)" >&2
 echo "[agent-primary-branch-guard]   to:   $new_branch" >&2
 echo "[agent-primary-branch-guard] The primary working tree must stay on its base/protected branch." >&2
-echo "[agent-primary-branch-guard] Use 'git worktree add' (or scripts/agent-branch-start.sh) for feature work." >&2
+echo "[agent-primary-branch-guard] Use 'git worktree add' (or gx branch start) for feature work." >&2
 
 if [[ "$is_agent" == "1" ]]; then
   echo "[agent-primary-branch-guard] Agent session detected — reverting to '$prev_branch'." >&2

package/templates/githooks/post-merge

@@ -32,17 +32,30 @@ if [[ "$branch" != "$base_branch" ]]; then
   exit 0
 fi
 
-cli_path="$repo_root/bin/multiagent-safety.js"
-if [[ ! -f "$cli_path" ]]; then
+if [[ -n "${GUARDEX_CLI_ENTRY:-}" ]]; then
+  node_bin="${GUARDEX_NODE_BIN:-node}"
+  if command -v "$node_bin" >/dev/null 2>&1; then
+    "$node_bin" "$GUARDEX_CLI_ENTRY" cleanup \
+      --target "$repo_root" \
+      --base "$base_branch" \
+      --include-pr-merged \
+      --keep-clean-worktrees >/dev/null 2>&1 || true
+  fi
   exit 0
 fi
 
-node_bin="${GUARDEX_NODE_BIN:-node}"
-if ! command -v "$node_bin" >/dev/null 2>&1; then
-  exit 0
+cli_bin="${GUARDEX_CLI_BIN:-}"
+if [[ -z "$cli_bin" ]]; then
+  if command -v gx >/dev/null 2>&1; then
+    cli_bin="gx"
+  elif command -v gitguardex >/dev/null 2>&1; then
+    cli_bin="gitguardex"
+  else
+    exit 0
+  fi
 fi
 
-"$node_bin" "$cli_path" cleanup \
+"$cli_bin" cleanup \
   --target "$repo_root" \
   --base "$base_branch" \
   --include-pr-merged \

package/templates/githooks/pre-commit

@@ -116,11 +116,11 @@ if [[ "$should_require_codex_agent_branch" == "1" && "${GUARDEX_ALLOW_CODEX_ON_N
 
       cat >&2 <<'MSG'
 [guardex-preedit-guard] Codex edit/commit detected on a protected branch.
-GuardeX requires Codex work to run from an isolated agent/* branch.
+GitGuardex requires Codex work to run from an isolated agent/* branch.
 Start the sub-branch/worktree with:
-  bash scripts/codex-agent.sh "<task-or-plan>" "<agent-name>"
+  gx branch start "<task-or-plan>" "<agent-name>"
 Or manually:
-  bash scripts/agent-branch-start.sh "<task-or-plan>" "<agent-name>"
+  gx branch start "<task-or-plan>" "<agent-name>"
 Then commit from the created agent/* branch.
 
 Temporary bypass (not recommended):
@@ -132,7 +132,7 @@ MSG
     cat >&2 <<'MSG'
 [codex-branch-guard] Codex agent commit blocked on non-agent branch.
 Use isolated branch/worktree first:
-  bash scripts/agent-branch-start.sh "<task-or-plan>" "<agent-name>"
+  gx branch start "<task-or-plan>" "<agent-name>"
 Then commit from the created agent/* branch.
 
 Temporary bypass (not recommended):
@@ -163,9 +163,9 @@ if [[ "$is_protected_branch" == "1" ]]; then
   cat >&2 <<'MSG'
 [agent-branch-guard] Direct commits on protected branches are blocked.
 Use an agent branch first:
-  bash scripts/agent-branch-start.sh "<task-or-plan>" "<agent-name>"
+  gx branch start "<task-or-plan>" "<agent-name>"
 After finishing work:
-  bash scripts/agent-branch-finish.sh
+  gx branch finish
 
 Temporary bypass (not recommended):
   ALLOW_COMMIT_ON_PROTECTED_BRANCH=1 git commit ...
@@ -177,7 +177,7 @@ if [[ "$is_agent_session" == "1" && "$branch" != agent/* ]]; then
   cat >&2 <<'MSG'
 [agent-branch-guard] Agent commits must run on dedicated agent/* branches.
 Start an agent branch first:
-  bash scripts/agent-branch-start.sh "<task-or-plan>" "<agent-name>"
+  gx branch start "<task-or-plan>" "<agent-name>"
 Then commit on that branch.
 
 Temporary bypass (not recommended):
@@ -199,7 +199,7 @@ if [[ "$branch" == agent/* ]]; then
     cat >&2 <<'MSG'
 [agent-branch-guard] Agent branch commits require file ownership locks.
 Claim files first:
-  python3 scripts/agent-file-locks.py claim --branch "$(git rev-parse --abbrev-ref HEAD)" <file...>
+  gx locks claim --branch "$(git rev-parse --abbrev-ref HEAD)" <file...>
 MSG
     exit 1
   fi

package/templates/scripts/agent-session-state.js

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+function resolveSessionSchemaModule() {
+  const candidates = [
+    path.resolve(__dirname, '..', 'vscode', 'guardex-active-agents', 'session-schema.js'),
+    path.resolve(__dirname, '..', 'templates', 'vscode', 'guardex-active-agents', 'session-schema.js'),
+  ];
+
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) {
+      return require(candidate);
+    }
+  }
+
+  throw new Error('Could not resolve Guardex active-agent session schema module.');
+}
+
+const sessionSchema = resolveSessionSchemaModule();
+
+function usage() {
+  return (
+    'Usage:\n' +
+    '  node scripts/agent-session-state.js start --repo <path> --branch <name> --task <task> --agent <agent> --worktree <path> --pid <pid> --cli <name>\n' +
+    '  node scripts/agent-session-state.js stop --repo <path> --branch <name>\n'
+  );
+}
+
+function parseOptions(argv) {
+  const options = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith('--')) {
+      throw new Error(`Unexpected argument: ${token}`);
+    }
+    const key = token.slice(2);
+    const value = argv[index + 1];
+    if (!value || value.startsWith('--')) {
+      throw new Error(`Missing value for --${key}`);
+    }
+    options[key] = value;
+    index += 1;
+  }
+  return options;
+}
+
+function requireOption(options, key) {
+  const value = options[key];
+  if (!value) {
+    throw new Error(`Missing required option --${key}`);
+  }
+  return value;
+}
+
+function writeSessionRecord(options) {
+  const repoRoot = requireOption(options, 'repo');
+  const branch = requireOption(options, 'branch');
+  const record = sessionSchema.buildSessionRecord({
+    repoRoot,
+    branch,
+    taskName: requireOption(options, 'task'),
+    agentName: requireOption(options, 'agent'),
+    worktreePath: requireOption(options, 'worktree'),
+    pid: requireOption(options, 'pid'),
+    cliName: requireOption(options, 'cli'),
+  });
+
+  const targetPath = sessionSchema.sessionFilePathForBranch(repoRoot, branch);
+  fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+  fs.writeFileSync(targetPath, `${JSON.stringify(record, null, 2)}\n`, 'utf8');
+}
+
+function removeSessionRecord(options) {
+  const repoRoot = requireOption(options, 'repo');
+  const branch = requireOption(options, 'branch');
+  const targetPath = sessionSchema.sessionFilePathForBranch(repoRoot, branch);
+  if (fs.existsSync(targetPath)) {
+    fs.unlinkSync(targetPath);
+  }
+}
+
+function main() {
+  const [command, ...rest] = process.argv.slice(2);
+  if (!command || ['-h', '--help', 'help'].includes(command)) {
+    process.stdout.write(usage());
+    return;
+  }
+
+  const options = parseOptions(rest);
+  if (command === 'start') {
+    writeSessionRecord(options);
+    return;
+  }
+  if (command === 'stop') {
+    removeSessionRecord(options);
+    return;
+  }
+
+  throw new Error(`Unknown subcommand: ${command}`);
+}
+
+try {
+  main();
+} catch (error) {
+  process.stderr.write(`[guardex-active-session] ${error.message}\n`);
+  process.stderr.write(usage());
+  process.exitCode = 1;
+}

package/templates/scripts/codex-agent.sh

@@ -6,6 +6,7 @@ AGENT_NAME="${GUARDEX_AGENT_NAME:-agent}"
 BASE_BRANCH="${GUARDEX_BASE_BRANCH:-}"
 BASE_BRANCH_EXPLICIT=0
 CODEX_BIN="${GUARDEX_CODEX_BIN:-codex}"
+NODE_BIN="${GUARDEX_NODE_BIN:-node}"
 AUTO_FINISH_RAW="${GUARDEX_CODEX_AUTO_FINISH:-true}"
 AUTO_REVIEW_ON_CONFLICT_RAW="${GUARDEX_CODEX_AUTO_REVIEW_ON_CONFLICT:-true}"
 AUTO_CLEANUP_RAW="${GUARDEX_CODEX_AUTO_CLEANUP:-true}"
@@ -143,6 +144,7 @@ if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
   exit 1
 fi
 repo_root="$(git rev-parse --show-toplevel)"
+active_session_state_script="${repo_root}/scripts/agent-session-state.js"
 
 guardex_env_helper="${repo_root}/scripts/guardex-env.sh"
 if [[ -f "$guardex_env_helper" ]]; then
@@ -446,6 +448,40 @@ has_origin_remote() {
   git -C "$repo_root" remote get-url origin >/dev/null 2>&1
 }
 
+run_active_session_state() {
+  local action="$1"
+  shift
+
+  if [[ ! -f "$active_session_state_script" ]]; then
+    return 0
+  fi
+  if ! command -v "$NODE_BIN" >/dev/null 2>&1; then
+    return 0
+  fi
+
+  "$NODE_BIN" "$active_session_state_script" "$action" "$@" >/dev/null 2>&1 || true
+}
+
+record_active_session_state() {
+  local wt="$1"
+  local branch="$2"
+
+  run_active_session_state \
+    start \
+    --repo "$repo_root" \
+    --branch "$branch" \
+    --task "$TASK_NAME" \
+    --agent "$AGENT_NAME" \
+    --worktree "$wt" \
+    --pid "$$" \
+    --cli "$CODEX_BIN"
+}
+
+clear_active_session_state() {
+  local branch="$1"
+  run_active_session_state stop --repo "$repo_root" --branch "$branch"
+}
+
 origin_remote_supports_pr_finish() {
   local origin_url
   origin_url="$(git -C "$repo_root" remote get-url origin 2>/dev/null || true)"
@@ -474,6 +510,31 @@ resolve_worktree_base_branch() {
   printf 'dev'
 }
 
+print_takeover_prompt() {
+  local wt="$1"
+  local branch="$2"
+  local base_branch change_slug change_artifact finish_cmd
+
+  base_branch="$(resolve_worktree_base_branch "$wt")"
+  if [[ -z "$base_branch" ]]; then
+    base_branch="dev"
+  fi
+
+  change_slug="$(resolve_openspec_change_slug "$branch")"
+  change_artifact="openspec/changes/${change_slug}/tasks.md"
+  if [[ ! -f "${wt}/${change_artifact}" ]]; then
+    change_artifact="openspec/changes/${change_slug}/notes.md"
+  fi
+  if [[ ! -f "${wt}/${change_artifact}" ]]; then
+    change_artifact="openspec/changes/${change_slug}/"
+  fi
+
+  finish_cmd="bash scripts/agent-branch-finish.sh --branch \"${branch}\" --base ${base_branch} --via-pr --wait-for-merge --cleanup"
+
+  echo "[codex-agent] Takeover sandbox: ${wt}"
+  echo "[codex-agent] Takeover prompt: Continue \`${change_slug}\` on branch \`${branch}\`. Work inside \`${wt}\`, review \`${change_artifact}\`, continue from the current state instead of creating a new sandbox, and when the work is done run \`${finish_cmd}\`."
+}
+
 sync_worktree_with_base() {
   local wt="$1"
   if ! has_origin_remote; then
@@ -833,6 +894,19 @@ if ! ensure_openspec_plan_workspace "$worktree_path" "$worktree_branch"; then
   exit 1
 fi
 
+active_session_recorded=0
+cleanup_active_session_state_on_exit() {
+  set +e
+  if [[ "${active_session_recorded:-0}" -eq 1 && -n "${worktree_branch:-}" && "${worktree_branch:-}" != "HEAD" ]]; then
+    clear_active_session_state "$worktree_branch"
+    active_session_recorded=0
+  fi
+}
+
+record_active_session_state "$worktree_path" "$worktree_branch"
+active_session_recorded=1
+trap cleanup_active_session_state_on_exit EXIT INT TERM
+
 echo "[codex-agent] Launching ${CODEX_BIN} in sandbox: $worktree_path"
 cd "$worktree_path"
 set +e
@@ -841,6 +915,8 @@ codex_exit="$?"
 set -e
 
 cd "$repo_root"
+cleanup_active_session_state_on_exit
+trap - EXIT INT TERM
 final_exit="$codex_exit"
 auto_finish_completed=0
 
@@ -901,6 +977,7 @@ else
     if [[ "$auto_finish_completed" -eq 1 ]]; then
       echo "[codex-agent] Branch kept intentionally. Cleanup on demand: gx cleanup --branch \"${worktree_branch}\""
     else
+      print_takeover_prompt "$worktree_path" "$worktree_branch"
       echo "[codex-agent] If finished, merge with: bash scripts/agent-branch-finish.sh --branch \"${worktree_branch}\" --base dev --via-pr --wait-for-merge"
       echo "[codex-agent] Cleanup on demand: gx cleanup --branch \"${worktree_branch}\""
     fi

package/templates/scripts/install-vscode-active-agents-extension.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+function parseOptions(argv) {
+  const options = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith('--')) {
+      throw new Error(`Unexpected argument: ${token}`);
+    }
+    const key = token.slice(2);
+    const value = argv[index + 1];
+    if (!value || value.startsWith('--')) {
+      throw new Error(`Missing value for --${key}`);
+    }
+    options[key] = value;
+    index += 1;
+  }
+  return options;
+}
+
+function resolveExtensionSource(repoRoot) {
+  const candidates = [
+    path.join(repoRoot, 'vscode', 'guardex-active-agents'),
+    path.join(repoRoot, 'templates', 'vscode', 'guardex-active-agents'),
+  ];
+
+  for (const candidate of candidates) {
+    if (fs.existsSync(path.join(candidate, 'package.json'))) {
+      return candidate;
+    }
+  }
+
+  throw new Error('Could not find the Guardex VS Code companion sources.');
+}
+
+function removeIfExists(targetPath) {
+  if (fs.existsSync(targetPath)) {
+    fs.rmSync(targetPath, { recursive: true, force: true });
+  }
+}
+
+function main() {
+  const repoRoot = path.resolve(__dirname, '..');
+  const options = parseOptions(process.argv.slice(2));
+  const sourceDir = resolveExtensionSource(repoRoot);
+  const manifest = JSON.parse(fs.readFileSync(path.join(sourceDir, 'package.json'), 'utf8'));
+  const extensionId = `${manifest.publisher}.${manifest.name}`;
+  const extensionsDir = path.resolve(
+    options['extensions-dir'] ||
+      process.env.GUARDEX_VSCODE_EXTENSIONS_DIR ||
+      process.env.VSCODE_EXTENSIONS_DIR ||
+      path.join(os.homedir(), '.vscode', 'extensions'),
+  );
+
+  fs.mkdirSync(extensionsDir, { recursive: true });
+  const targetDir = path.join(extensionsDir, `${extensionId}-${manifest.version}`);
+
+  for (const entry of fs.readdirSync(extensionsDir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+    if (entry.name === path.basename(targetDir)) {
+      continue;
+    }
+    if (entry.name.startsWith(`${extensionId}-`)) {
+      removeIfExists(path.join(extensionsDir, entry.name));
+    }
+  }
+
+  removeIfExists(targetDir);
+  fs.cpSync(sourceDir, targetDir, {
+    recursive: true,
+    force: true,
+    preserveTimestamps: true,
+  });
+
+  process.stdout.write(
+    `[guardex-active-agents] Installed ${extensionId}@${manifest.version} to ${targetDir}\n` +
+      '[guardex-active-agents] Reload the VS Code window to activate the Source Control companion.\n',
+  );
+}
+
+try {
+  main();
+} catch (error) {
+  process.stderr.write(`[guardex-active-agents] ${error.message}\n`);
+  process.exitCode = 1;
+}

package/templates/scripts/openspec/init-change-workspace.sh

@@ -1,14 +1,15 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-if [[ $# -lt 1 || $# -gt 2 ]]; then
-  echo "Usage: $0 <change-slug> [capability-slug]"
-  echo "Example: $0 add-dashboard-live-usage runtime-migration"
+if [[ $# -lt 1 || $# -gt 3 ]]; then
+  echo "Usage: $0 <change-slug> [capability-slug] [agent-branch]"
+  echo "Example: $0 add-dashboard-live-usage runtime-migration agent/claude-odin/add-dashboard-live-usage-123456"
   exit 1
 fi
 
 CHANGE_SLUG="$1"
 CAPABILITY_SLUG="${2:-$CHANGE_SLUG}"
+AGENT_BRANCH="${3:-agent/<your-name>/<branch-slug>}"
 
 if [[ "$CHANGE_SLUG" =~ [^a-z0-9-] ]]; then
   echo "Error: change slug must be kebab-case (lowercase letters, numbers, hyphens)."
@@ -20,11 +21,39 @@ if [[ "$CAPABILITY_SLUG" =~ [^a-z0-9-] ]]; then
   exit 1
 fi
 
+resolve_base_branch() {
+  local branch="$1"
+  local base_branch=""
+
+  if [[ -n "$branch" ]] && [[ "$branch" != "agent/<your-name>/<branch-slug>" ]]; then
+    base_branch="$(git config --get "branch.${branch}.guardexBase" || true)"
+  fi
+  if [[ -z "$base_branch" ]]; then
+    base_branch="$(git config --get multiagent.baseBranch || true)"
+  fi
+  if [[ -z "$base_branch" ]]; then
+    base_branch="dev"
+  fi
+
+  printf '%s' "$base_branch"
+}
+
 CHANGE_DIR="openspec/changes/${CHANGE_SLUG}"
 SPEC_DIR="${CHANGE_DIR}/specs/${CAPABILITY_SLUG}"
 TODAY="$(date -u +%Y-%m-%d)"
-
-mkdir -p "$SPEC_DIR"
+BASE_BRANCH="$(resolve_base_branch "$AGENT_BRANCH")"
+
+MINIMAL_RAW="${GUARDEX_OPENSPEC_MINIMAL:-0}"
+case "$(printf '%s' "$MINIMAL_RAW" | tr '[:upper:]' '[:lower:]')" in
+  1|true|yes|on) MINIMAL=1 ;;
+  *) MINIMAL=0 ;;
+esac
+
+if [[ "$MINIMAL" -eq 1 ]]; then
+  mkdir -p "$CHANGE_DIR"
+else
+  mkdir -p "$SPEC_DIR"
+fi
 
 if [[ ! -f "${CHANGE_DIR}/.openspec.yaml" ]]; then
   cat > "${CHANGE_DIR}/.openspec.yaml" <<YAMLEOF
@@ -33,6 +62,32 @@ created: ${TODAY}
 YAMLEOF
 fi
 
+if [[ "$MINIMAL" -eq 1 ]]; then
+  if [[ ! -f "${CHANGE_DIR}/notes.md" ]]; then
+    cat > "${CHANGE_DIR}/notes.md" <<NOTESEOF
+# ${CHANGE_SLUG} (minimal / T1)
+
+Branch: \`${AGENT_BRANCH}\`
+
+Describe the change in a sentence or two. Commit message is the spec of record.
+
+## Handoff
+
+- Handoff: change=\`${CHANGE_SLUG}\`; branch=\`${AGENT_BRANCH}\`; scope=\`TODO\`; action=\`continue this sandbox or finish cleanup after a usage-limit/manual takeover\`.
+- Copy prompt: Continue \`${CHANGE_SLUG}\` on branch \`${AGENT_BRANCH}\`. Work inside the existing sandbox, review \`openspec/changes/${CHANGE_SLUG}/notes.md\`, continue from the current state instead of creating a new sandbox, and when the work is done run \`gx branch finish --branch ${AGENT_BRANCH} --base ${BASE_BRANCH} --via-pr --wait-for-merge --cleanup\`.
+
+## Cleanup
+
+- [ ] Run: \`gx branch finish --branch ${AGENT_BRANCH} --base ${BASE_BRANCH} --via-pr --wait-for-merge --cleanup\`
+- [ ] Record PR URL + \`MERGED\` state in the completion handoff.
+- [ ] Confirm sandbox worktree is gone (\`git worktree list\`, \`git branch -a\`).
+NOTESEOF
+  fi
+  echo "[gitguardex] OpenSpec change workspace (minimal) ready: ${CHANGE_DIR}"
+  echo "[gitguardex] Notes-only scaffold: ${CHANGE_DIR}/notes.md"
+  exit 0
+fi
+
 if [[ ! -f "${CHANGE_DIR}/proposal.md" ]]; then
   cat > "${CHANGE_DIR}/proposal.md" <<PROPOSALEOF
 ## Why
@@ -51,6 +106,19 @@ fi
 
 if [[ ! -f "${CHANGE_DIR}/tasks.md" ]]; then
   cat > "${CHANGE_DIR}/tasks.md" <<TASKSEOF
+## Definition of Done
+
+This change is complete only when **all** of the following are true:
+
+- Every checkbox below is checked.
+- The agent branch reaches \`MERGED\` state on \`origin\` and the PR URL + state are recorded in the completion handoff.
+- If any step blocks (test failure, conflict, ambiguous result), append a \`BLOCKED:\` line under section 4 explaining the blocker and **STOP**. Do not tick remaining cleanup boxes; do not silently skip the cleanup pipeline.
+
+## Handoff
+
+- Handoff: change=\`${CHANGE_SLUG}\`; branch=\`${AGENT_BRANCH}\`; scope=\`TODO\`; action=\`continue this sandbox or finish cleanup after a usage-limit/manual takeover\`.
+- Copy prompt: Continue \`${CHANGE_SLUG}\` on branch \`${AGENT_BRANCH}\`. Work inside the existing sandbox, review \`openspec/changes/${CHANGE_SLUG}/tasks.md\`, continue from the current state instead of creating a new sandbox, and when the work is done run \`gx branch finish --branch ${AGENT_BRANCH} --base ${BASE_BRANCH} --via-pr --wait-for-merge --cleanup\`.
+
 ## 1. Specification
 
 - [ ] 1.1 Finalize proposal scope and acceptance criteria for \`${CHANGE_SLUG}\`.
@@ -67,11 +135,11 @@ if [[ ! -f "${CHANGE_DIR}/tasks.md" ]]; then
 - [ ] 3.2 Run \`openspec validate ${CHANGE_SLUG} --type change --strict\`.
 - [ ] 3.3 Run \`openspec validate --specs\`.
 
-## 4. Completion
+## 4. Cleanup (mandatory; run before claiming completion)
 
-- [ ] 4.1 Finish the agent branch via PR merge + cleanup (\`gx finish --via-pr --wait-for-merge --cleanup\` or \`bash scripts/agent-branch-finish.sh --branch <agent-branch> --base <base-branch> --via-pr --wait-for-merge --cleanup\`).
-- [ ] 4.2 Record PR URL + final \`MERGED\` state in the completion handoff.
-- [ ] 4.3 Confirm sandbox cleanup (\`git worktree list\`, \`git branch -a\`) or capture a \`BLOCKED:\` handoff if merge/cleanup is pending.
+- [ ] 4.1 Run the cleanup pipeline: \`gx branch finish --branch ${AGENT_BRANCH} --base ${BASE_BRANCH} --via-pr --wait-for-merge --cleanup\`. This handles commit -> push -> PR create -> merge wait -> worktree prune in one invocation.
+- [ ] 4.2 Record the PR URL and final merge state (\`MERGED\`) in the completion handoff.
+- [ ] 4.3 Confirm the sandbox worktree is gone (\`git worktree list\` no longer shows the agent path; \`git branch -a\` shows no surviving local/remote refs for the branch).
 TASKSEOF
 fi