gennady 0.8.2 → 0.8.4

package/dist/ai/skills/sdd-execute/scripts/_sdd-lib.sh

@@ -0,0 +1,60 @@
+# @file: Shared SDD artifact parsers — sourced by scan.sh / check.sh, never executed directly.
+# @consumers: check.sh (canonical), scan.sh (migration pending).
+# @contract: pure functions of file contents; no stdout side effects beyond the echoed result.
+#
+# Why this lib exists:
+#   - check.sh and scan.sh both parse ticket Meta.Status, Task-ID, tracker rows, file headers.
+#   - One implementation here = no drift between the two SDD tree tools (the whole point of
+#     `sdd check`: a single source of mechanical truth that both sdd-check and sdd-audit consume).
+#
+# macOS bash 3.2 compatible: grep -E / sed -E / awk only. No grep -P, no GNU sed -i.
+
+# Extract Meta.Status flag from a ticket. Echoes: DONE | TODO | IN_PROGRESS | BLOCKED | UNKNOWN
+sdd_lib_status() {
+    local f="$1" line flag
+    line=$(head -60 "$f" 2>/dev/null | grep -m1 -E '^\s*-?\s*\*?\*?Status:\*?\*?\s*\[.\]' || true)
+    [[ -z "$line" ]] && { echo "UNKNOWN"; return; }
+    flag=$(echo "$line" | sed -nE 's/.*\[(.)\].*/\1/p')
+    case "$flag" in
+        x|X) echo "DONE" ;;
+        ' ') echo "TODO" ;;
+        '~') echo "IN_PROGRESS" ;;
+        '!') echo "BLOCKED" ;;
+        *)   echo "UNKNOWN" ;;
+    esac
+}
+
+# Extract Task-ID (TSK-NN) from a ticket Meta. Echoes the ID or empty string.
+sdd_lib_task_id() {
+    local f="$1"
+    head -30 "$f" 2>/dev/null \
+        | grep -m1 -oE 'Task-ID:\*?\*?\s*TSK-[0-9]+' \
+        | grep -oE 'TSK-[0-9]+' || true
+}
+
+# Map a tracker-row status cell (`[x]` DONE etc.) to canonical token for ONE Task-ID.
+# Args: <tracker-file> <TSK-NN>. Echoes DONE|TODO|IN_PROGRESS|BLOCKED|UNKNOWN (UNKNOWN if no row).
+sdd_lib_tracker_status() {
+    local tr="$1" id="$2" row flag
+    # Row form: | [TSK-NN](...) | ... | `[x]` DONE | ... |  (also bare TSK-NN)
+    row=$(grep -m1 -E "\|[[:space:]]*\[?${id}[]\(]" "$tr" 2>/dev/null || true)
+    [[ -z "$row" ]] && { echo "UNKNOWN"; return; }
+    flag=$(echo "$row" | sed -nE 's/.*`?\[(.)\]`?[[:space:]]+(DONE|TODO|IN_PROGRESS|BLOCKED).*/\1/p')
+    case "$flag" in
+        x|X) echo "DONE" ;;
+        ' ') echo "TODO" ;;
+        '~') echo "IN_PROGRESS" ;;
+        '!') echo "BLOCKED" ;;
+        *)   echo "UNKNOWN" ;;
+    esac
+}
+
+# Header-trio presence for a source file. Echoes three space-separated flags: <file> <consumers> <tasks>
+# Each flag is 1 (marker present) or 0 (absent). `@tasks: N/A` counts as present.
+sdd_lib_header_flags() {
+    local f="$1" hf=0 hc=0 ht=0
+    head -20 "$f" 2>/dev/null | grep -qE '@file:'      && hf=1
+    head -20 "$f" 2>/dev/null | grep -qE '@consumers:'  && hc=1
+    head -20 "$f" 2>/dev/null | grep -qE '@tasks:'      && ht=1
+    echo "$hf $hc $ht"
+}

package/dist/ai/skills/sdd-execute/scripts/check.sh

@@ -0,0 +1,238 @@
+#!/usr/bin/env bash
+# @file: Deterministic SDD mechanical checks shared by sdd-check (whole tree) and sdd-audit (scoped).
+# @consumers: sdd-check skill (whole-tree preflight); sdd-audit directive STEP_2_5 (scoped pre-pass).
+# @contract: AX_BASH_NO_SILENT_EMPTY. Single source of mechanical truth — neither skill re-implements
+#            header presence, Task-ID integrity, or tracker sync. Pure function of files on disk.
+#
+# Three modes:
+#   check.sh [project-root]          — whole tree: TASKID + TRACKER_SYNC (all tickets) + HEADERS (all marker-bearing src)
+#   check.sh --task <TSK-NN> [root]  — one ticket: TASKID (collision/orphan-for-its-refs) + TRACKER_SYNC for that id
+#   check.sh --files <f1> [f2 ...]   — header-trio presence for an explicit file list (audit passes its git-diff scope)
+#
+# Output sections (TSV, machine-readable, stable):
+#   [HEADERS]      — file \t has_file \t has_consumers \t has_tasks \t verdict(OK|PARTIAL|NONE)
+#   [TASKID]       — kind(orphan|collision) \t id \t detail
+#   [TRACKER_SYNC] — task_id \t ticket_status \t tracker_status \t match(YES|NO|NO_ROW)
+#   [SUMMARY]      — key=value totals + findings count
+#
+# Exit codes:
+#   0 — all checks clean (zero findings)
+#   3 — one or more findings (desync / orphan / collision / partial-or-missing header)
+#   2 — structural failure (bad root / not an SDD project)
+#   4 — bad invocation
+
+set -uo pipefail
+
+PROG="check"
+VERSION="1"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=_sdd-lib.sh
+. "$SCRIPT_DIR/_sdd-lib.sh"
+
+# ---------------------------------------------------------------------------
+# Argument parsing → MODE
+# ---------------------------------------------------------------------------
+
+MODE="tree"
+TASK_ID=""
+FILES=()
+ROOT="."
+
+case "${1:-}" in
+    --task)
+        MODE="task"
+        TASK_ID="${2:-}"
+        ROOT="${3:-.}"
+        if [[ -z "$TASK_ID" || ! "$TASK_ID" =~ ^TSK-[0-9]+$ ]]; then
+            cat <<EOF
+[$PROG] BAD_INVOCATION
+  expected: $PROG --task TSK-NN [project-root]
+  got:      $PROG --task '${TASK_ID:-}' ...
+Required action: pass a Task-ID of the form TSK-<number>.
+EOF
+            exit 4
+        fi
+        ;;
+    --files)
+        MODE="files"
+        shift 2>/dev/null || true
+        FILES=("$@")
+        if [[ ${#FILES[@]} -eq 0 ]]; then
+            cat <<EOF
+[$PROG] BAD_INVOCATION
+  expected: $PROG --files <file1> [file2 ...]
+  got:      $PROG --files (no files)
+Required action: pass at least one source file to check headers on.
+EOF
+            exit 4
+        fi
+        ;;
+    --*)
+        cat <<EOF
+[$PROG] BAD_INVOCATION
+  unknown flag: $1
+  expected: $PROG [project-root] | $PROG --task TSK-NN [root] | $PROG --files <files...>
+EOF
+        exit 4
+        ;;
+    *)
+        MODE="tree"
+        ROOT="${1:-.}"
+        ;;
+esac
+
+FINDINGS=0
+
+# ---------------------------------------------------------------------------
+# Mode: --files  → HEADERS only
+# ---------------------------------------------------------------------------
+
+emit_header_row() {
+    local f="$1" flags hf hc ht verdict
+    flags=$(sdd_lib_header_flags "$f")
+    hf=$(echo "$flags" | cut -d' ' -f1)
+    hc=$(echo "$flags" | cut -d' ' -f2)
+    ht=$(echo "$flags" | cut -d' ' -f3)
+    if [[ "$hf" -eq 1 && "$ht" -eq 1 ]]; then
+        verdict="OK"   # @consumers is MINOR; @file + @tasks are the required pair
+    elif [[ "$hf" -eq 0 && "$hc" -eq 0 && "$ht" -eq 0 ]]; then
+        verdict="NONE"
+    else
+        verdict="PARTIAL"; FINDINGS=$((FINDINGS+1))
+    fi
+    printf '%s\t%d\t%d\t%d\t%s\n' "$f" "$hf" "$hc" "$ht" "$verdict"
+}
+
+if [[ "$MODE" == "files" ]]; then
+    printf '# sdd check v%s (mode=files)\n' "$VERSION"
+    printf '\n[HEADERS]\n# file\thas_file\thas_consumers\thas_tasks\tverdict\n'
+    for f in "${FILES[@]}"; do
+        if [[ ! -f "$f" ]]; then
+            printf '%s\t-\t-\t-\tMISSING_FILE\n' "$f"; FINDINGS=$((FINDINGS+1)); continue
+        fi
+        emit_header_row "$f"
+    done
+    printf '\n[SUMMARY]\nmode=files\nfiles_checked=%d\nfindings=%d\n' "${#FILES[@]}" "$FINDINGS"
+    [[ "$FINDINGS" -gt 0 ]] && exit 3 || exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# tree / task modes need an SDD root
+# ---------------------------------------------------------------------------
+
+if [[ ! -d "$ROOT" ]]; then
+    echo "[$PROG] BAD_ROOT: $ROOT is not a directory"; exit 2
+fi
+ROOT_ABS="$(cd "$ROOT" && pwd)"
+if [[ ! -d "$ROOT_ABS/tasks" && ! -d "$ROOT_ABS/specs" ]]; then
+    cat <<EOF
+[$PROG] NOT_AN_SDD_PROJECT
+  root: $ROOT_ABS
+  reason: neither tasks/ nor specs/ found
+Required action: run from an SDD project root, or pass it explicitly.
+EOF
+    exit 2
+fi
+
+printf '# sdd check v%s (mode=%s%s)\n' "$VERSION" "$MODE" "$([[ "$MODE" == task ]] && echo " $TASK_ID")"
+printf 'ROOT=%s\n' "$ROOT_ABS"
+
+TASK_FILES=$(find -L "$ROOT_ABS/tasks" -name '*.task-*.md' -type f 2>/dev/null | sort || true)
+
+# ---------------------------------------------------------------------------
+# [TASKID] — collisions (global) + orphan @tasks references
+# ---------------------------------------------------------------------------
+
+printf '\n[TASKID]\n# kind\tid\tdetail\n'
+
+# Build id → files map to detect collisions (two tickets declaring same Task-ID).
+COLLISION_TMP="$(mktemp -t sdd-check-ids.XXXXXX)"
+trap 'rm -f "$COLLISION_TMP"' EXIT
+while IFS= read -r f; do
+    [[ -z "$f" ]] && continue
+    id=$(sdd_lib_task_id "$f")
+    [[ -z "$id" ]] && continue
+    printf '%s\t%s\n' "$id" "${f#$ROOT_ABS/}" >> "$COLLISION_TMP"
+done <<< "$TASK_FILES"
+
+# Collisions: ids appearing on >1 ticket. In task mode, restrict to TASK_ID.
+while IFS= read -r id; do
+    [[ -z "$id" ]] && continue
+    [[ "$MODE" == "task" && "$id" != "$TASK_ID" ]] && continue
+    files=$(awk -F'\t' -v k="$id" '$1==k {print $2}' "$COLLISION_TMP" | paste -sd',' -)
+    printf 'collision\t%s\t%s\n' "$id" "$files"
+    FINDINGS=$((FINDINGS+1))
+done < <(cut -f1 "$COLLISION_TMP" | sort | uniq -d)
+
+# Orphans: @tasks: TSK-NN in source with no matching ticket file.
+# Whole-tree mode only (task mode trusts its own ticket exists).
+if [[ "$MODE" == "tree" ]]; then
+    known_ids=$(cut -f1 "$COLLISION_TMP" | sort -u)
+    # Collect @tasks references from source files (exclude heavy dirs).
+    refs=$(grep -rhoE '@tasks:[^@]*' "$ROOT_ABS" \
+              --include='*.ts' --include='*.js' --include='*.sh' --include='*.go' \
+              --exclude-dir=node_modules --exclude-dir=.git --exclude-dir=dist \
+              --exclude-dir=worktrees --exclude-dir=.claude 2>/dev/null \
+            | grep -oE 'TSK-[0-9]+' | sort -u || true)
+    while IFS= read -r rid; do
+        [[ -z "$rid" ]] && continue
+        if ! echo "$known_ids" | grep -qx "$rid"; then
+            printf 'orphan\t%s\t@tasks reference with no tasks/**/*.task-*.md\n' "$rid"
+            FINDINGS=$((FINDINGS+1))
+        fi
+    done <<< "$refs"
+fi
+
+# ---------------------------------------------------------------------------
+# [TRACKER_SYNC] — ticket Meta.Status vs tracker-row status
+# ---------------------------------------------------------------------------
+
+printf '\n[TRACKER_SYNC]\n# task_id\tticket_status\ttracker_status\tmatch\n'
+
+sync_one() {
+    local f="$1" id ticket_status scope tracker tracker_status match
+    id=$(sdd_lib_task_id "$f")
+    [[ -z "$id" ]] && return
+    ticket_status=$(sdd_lib_status "$f")
+    # scope = first path segment under tasks/
+    scope=$(echo "${f#$ROOT_ABS/tasks/}" | awk -F/ '{print $1}')
+    tracker="$ROOT_ABS/tasks/$scope/README.md"
+    if [[ ! -f "$tracker" ]]; then
+        printf '%s\t%s\t-\tNO_ROW\n' "$id" "$ticket_status"; FINDINGS=$((FINDINGS+1)); return
+    fi
+    tracker_status=$(sdd_lib_tracker_status "$tracker" "$id")
+    if [[ "$ticket_status" == "UNKNOWN" ]]; then
+        # Old-template ticket lacking a parseable Meta **Status:** — cannot compare.
+        # Not a desync finding (mirrors scan.sh WARN, not ERROR); surface as UNPARSEABLE.
+        match="UNPARSEABLE"
+    elif [[ "$tracker_status" == "UNKNOWN" ]]; then
+        match="NO_ROW"; FINDINGS=$((FINDINGS+1))
+    elif [[ "$tracker_status" == "$ticket_status" ]]; then
+        match="YES"
+    else
+        match="NO"; FINDINGS=$((FINDINGS+1))
+    fi
+    printf '%s\t%s\t%s\t%s\n' "$id" "$ticket_status" "$tracker_status" "$match"
+}
+
+while IFS= read -r f; do
+    [[ -z "$f" ]] && continue
+    if [[ "$MODE" == "task" ]]; then
+        [[ "$(sdd_lib_task_id "$f")" == "$TASK_ID" ]] || continue
+    fi
+    sync_one "$f"
+done <<< "$TASK_FILES"
+
+# [HEADERS] is intentionally NOT run in tree mode: "which files must carry @tasks"
+# is a policy (task-generated vs hand-authored), not a mechanical fact. Header presence
+# is meaningful only against a known in-scope file set — provided by audit via --files.
+
+# ---------------------------------------------------------------------------
+# [SUMMARY]
+# ---------------------------------------------------------------------------
+
+printf '\n[SUMMARY]\nmode=%s\n' "$MODE"
+[[ "$MODE" == "task" ]] && printf 'task=%s\n' "$TASK_ID"
+printf 'findings=%d\n' "$FINDINGS"
+
+[[ "$FINDINGS" -gt 0 ]] && exit 3 || exit 0

package/dist/ai/skills/sdd-execute/scripts/sdd

@@ -9,6 +9,7 @@
 #   sdd verify <file>...                — comprehensive gate: typecheck + gennady lint + forbidden_grep
 #   sdd check-blockers <ticket-file>    — scan Execution Log for unresolved BLOCKER entries
 #   sdd scan [project-root]             — emit comprehensive project snapshot (single rich call)
+#   sdd check [root|--task TSK-NN|--files f...] — deterministic mechanical checks (task-id, tracker-sync, headers)
 #   sdd help                            — print this help
 #
 # Why this wrapper exists:
@@ -44,6 +45,9 @@ case "$SUBCMD" in
     scan)
         exec "$SCRIPT_DIR/scan.sh" "$@"
         ;;
+    check)
+        exec "$SCRIPT_DIR/check.sh" "$@"
+        ;;
     help|--help|-h)
         cat <<'EOF'
 sdd — SDD command dispatcher
@@ -80,6 +84,14 @@ SUBCOMMANDS
                                   unparseable Meta.Status, broken spec links) are surfaced
                                   in [WARNINGS]. Defaults to current directory.
 
+    check [root]                Deterministic mechanical checks — the single source of
+      check --task TSK-NN [root]   mechanical truth shared by sdd-check (whole tree) and
+      check --files <f...>         sdd-audit (scoped). Emits [TASKID] (collisions, orphan
+                                  @tasks refs), [TRACKER_SYNC] (ticket Meta.Status vs tracker
+                                  row), and — in --files mode — [HEADERS] (@file/@consumers/
+                                  @tasks presence on a caller-supplied in-scope file list).
+                                  Exit 0 clean, 3 findings, 2 structural, 4 bad invocation.
+
     check-blockers <ticket>     Scan ticket Execution Log for unresolved BLOCKER entries.
                                   A BLOCKER is considered RESOLVED if a later Round contains
                                   a "✅ RESOLVED" entry referencing it. Returns list of

package/dist/ai/skills/sdd-hooks-install/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: sdd-hooks-install
+description: Install Claude Code hooks for live SDD subagent progress streaming. Adds PreToolUse / PostToolUse / SubagentStop entries to project's .claude/settings.json (merging with existing config), ensures .claude/sdd-progress.ndjson is gitignored, prints the operator's tail command. Use once per project before running /sdd-execute or /sdd-execute-batch when live progress visibility is wanted. Idempotent — safe to re-run.
+---
+
+<SDDHooksInstaller role="config-bootstrapper">
+You install hooks into the CURRENT project to enable live SDD progress tailing. You do NOT install global hooks (those would fire on every project). Idempotent — re-running detects existing entries and skips duplicates.
+
+<Protocol>
+1. **Verify project context:**
+   - cwd has `.git/` OR a `.claude/` directory OR an `.ai/` directory → proceed.
+   - Otherwise → halt: "Not a project root. Run from project's working directory."
+
+2. **Ensure `.claude/` exists:**
+   - `mkdir -p .claude`
+
+3. **Patch `.claude/settings.json`:**
+   - File missing → write a fresh one with the hooks block below.
+   - File exists → parse JSON. Merge: under `.hooks`, add `PreToolUse`, `PostToolUse`, `SubagentStop` entries. If a matcher with same `command` already exists, skip. Preserve existing hooks.
+   - Write back with 2-space indent.
+
+   Hooks block to add:
+   ```jsonc
+   {
+     "hooks": {
+       "PreToolUse": [
+         {
+           "matcher": "*",
+           "hooks": [
+             {
+               "type": "command",
+               "command": "jq -nc --arg ts \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\" --arg tool \"$CLAUDE_HOOK_TOOL_NAME\" --arg agent \"${CLAUDE_HOOK_PARENT_TOOL_USE_ID:-}\" '{ts:$ts, kind:\"pre\", tool:$tool, agent:$agent}' >> .claude/sdd-progress.ndjson"
+             }
+           ]
+         }
+       ],
+       "PostToolUse": [
+         {
+           "matcher": "*",
+           "hooks": [
+             {
+               "type": "command",
+               "command": "jq -nc --arg ts \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\" --arg tool \"$CLAUDE_HOOK_TOOL_NAME\" --arg agent \"${CLAUDE_HOOK_PARENT_TOOL_USE_ID:-}\" '{ts:$ts, kind:\"post\", tool:$tool, agent:$agent}' >> .claude/sdd-progress.ndjson"
+             }
+           ]
+         }
+       ],
+       "SubagentStop": [
+         {
+           "hooks": [
+             {
+               "type": "command",
+               "command": "jq -nc --arg ts \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\" --arg sess \"${CLAUDE_HOOK_SESSION_ID:-}\" '{ts:$ts, kind:\"subagent_stop\", session:$sess}' >> .claude/sdd-progress.ndjson"
+             }
+           ]
+         }
+       ]
+     }
+   }
+   ```
+
+4. **Patch `.gitignore`:**
+   - Append `.claude/sdd-progress.ndjson` if not already listed.
+   - Create `.gitignore` with that single line if missing.
+
+5. **Verify `jq` is available** (Bash `command -v jq`). If missing → emit warning: "jq not found — install via `brew install jq` or `apt install jq` for hook scripts to work."
+
+6. **Print to operator** (final message):
+   ```
+   ✅ SDD hooks installed in <project-root>/.claude/settings.json
+   ✅ .gitignore updated to exclude sdd-progress.ndjson
+
+   To watch live progress in a second terminal:
+       tail -f .claude/sdd-progress.ndjson | jq -r '"\(.ts) | \(.kind) | \(.tool // .session) | agent=\(.agent // "-")"'
+
+   Now run /sdd-execute <TSK-NN> or /sdd-execute-batch in this terminal.
+
+   To uninstall: edit .claude/settings.json and remove the SDD entries.
+   ```
+</Protocol>
+
+<HardForbidden>
+- Modifying global `~/.claude/settings.json` (this is per-project setup).
+- Overwriting existing settings.json — must merge, preserving operator's other hooks.
+- Adding the file outside .gitignore (would commit operator activity logs).
+- Running the install if jq is unavailable without the warning (hooks would silently fail).
+</HardForbidden>
+</SDDHooksInstaller>

package/dist/ai/skills/workspace-permission-setup/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: workspace-permission-setup
+description: Configure .claude/settings.json so the agent works autonomously inside the current repository while being auto-denied access to anything outside it (home directory, system paths, network, secrets). Use when the user wants to enable AI-first development with minimal permission prompts, scope the agent to a workspace, set up safe autonomy for a project, stop the agent from leaving the repo, reduce repetitive approval requests, or harden permissions for a codebase.
+---
+
+# Workspace Permission Setup
+
+Set up `.claude/settings.json` so the agent operates fully autonomously **inside** the current repository, and is **auto-denied** (not prompted) for anything **outside** it. Goal: enable AI-first development without sacrificing safety.
+
+## Core principle
+
+- **Wide allow inside repo** — file edits, project tooling, git, common shell utilities.
+- **Hard deny outside repo** — `~/`, `/etc`, `/var`, `.ssh`, `.aws`, network commands, `WebFetch`/`WebSearch`, secrets.
+- `deny` always wins over `allow` — the agent gets a refusal, not a prompt, so the user is not interrupted.
+
+## Workflow
+
+Always run all six steps in order. Never write to disk before Step 5 user approval.
+
+### Step 1 — Detect project context
+
+Determine repo root and stack so allow-list is tailored, not generic.
+
+```bash
+git rev-parse --show-toplevel 2>/dev/null || pwd
+ls -la package.json pyproject.toml Cargo.toml go.mod Gemfile pom.xml build.gradle Makefile Dockerfile docker-compose.yml mise.toml .tool-versions 2>/dev/null
+ls -la .claude/ 2>/dev/null
+```
+
+Map detection → allow additions:
+
+| Detected | Add to allow |
+|---|---|
+| `package.json` | `Bash(npm:*)`, `Bash(npx:*)`, `Bash(pnpm:*)`, `Bash(yarn:*)`, `Bash(node:*)` |
+| `pyproject.toml` / `requirements.txt` | `Bash(python:*)`, `Bash(python3:*)`, `Bash(pip:*)`, `Bash(uv:*)`, `Bash(poetry:*)`, `Bash(pytest:*)` |
+| `Cargo.toml` | `Bash(cargo:*)`, `Bash(rustc:*)` |
+| `go.mod` | `Bash(go:*)`, `Bash(gofmt:*)` |
+| `Gemfile` | `Bash(bundle:*)`, `Bash(rake:*)`, `Bash(rspec:*)` |
+| `Makefile` | `Bash(make:*)` |
+| `Dockerfile` / `docker-compose.yml` | (do **not** auto-allow `docker` — ask in Step 4) |
+| `mise.toml` / `.tool-versions` | `Bash(mise:*)` |
+
+Also read existing `.claude/settings.json` and `.claude/settings.local.json`. **Preserve** other sections — only the `permissions` block is replaced.
+
+### Step 2 — Harvest from transcript history
+
+Invoke the `fewer-permission-prompts` skill via the Skill tool. It scans recent transcripts and extracts safe read-only commands the user has been approving repeatedly. Capture its proposal but **do not** let it write — we will merge into our config in Step 3.
+
+If the skill is not available or returns nothing useful, skip — Steps 1 and 3 give a working baseline.
+
+### Step 3 — Build the proposed config
+
+Three sources merged into one block:
+
+1. **Universal scoping** (deny + baseline allow — always present).
+2. **Project-specific allow** (from Step 1).
+3. **Transcript-derived allow** (from Step 2).
+
+#### Universal scoping deny — always include
+
+```json
+"deny": [
+  "WebFetch",
+  "WebSearch",
+
+  "Read(~/**)",
+  "Edit(~/**)",
+  "Write(~/**)",
+  "Read(/etc/**)",
+  "Read(/var/**)",
+  "Read(/private/**)",
+  "Read(/tmp/**)",
+
+  "Read(./.env*)",
+  "Read(./**/.env*)",
+  "Read(./.git/config)",
+
+  "Bash(curl:*)",
+  "Bash(wget:*)",
+  "Bash(ssh:*)",
+  "Bash(scp:*)",
+  "Bash(rsync:*)",
+  "Bash(nc:*)",
+  "Bash(cd ..*)",
+  "Bash(cd /*)",
+  "Bash(cd ~*)",
+  "Bash(rm -rf:*)",
+  "Bash(sudo:*)"
+]
+```
+
+If sensitive directories exist on the machine (`~/.ssh`, `~/.aws`, `~/.gnupg`, `~/.config`, `~/Library`), add explicit absolute-path denies — `~` patterns may not always expand, so be belt-and-suspenders:
+
+```json
+"Read(/Users/<user>/.ssh/**)",
+"Read(/Users/<user>/.aws/**)",
+"Read(/Users/<user>/.gnupg/**)",
+"Read(/Users/<user>/.config/**)",
+"Read(/Users/<user>/Library/**)"
+```
+
+Use `$HOME` or detect actual user from `whoami` / `echo $HOME`.
+
+#### Universal allow baseline — always include
+
+```json
+"allow": [
+  "Read",
+  "Grep",
+  "Glob",
+  "Edit",
+  "Write",
+  "Bash(git:*)",
+  "Bash(ls:*)",
+  "Bash(cat:*)",
+  "Bash(head:*)",
+  "Bash(tail:*)",
+  "Bash(grep:*)",
+  "Bash(rg:*)",
+  "Bash(find . *)",
+  "Bash(sed:*)",
+  "Bash(awk:*)",
+  "Bash(jq:*)",
+  "Bash(diff:*)",
+  "Bash(wc:*)",
+  "Bash(echo:*)",
+  "Bash(pwd)",
+  "Bash(mkdir:*)",
+  "Bash(touch:*)",
+  "Bash(mv:*)",
+  "Bash(cp:*)"
+]
+```
+
+#### Default mode
+
+```json
+"defaultMode": "acceptEdits"
+```
+
+File edits inside the repo no longer prompt.
+
+### Step 4 — Interactive review with the user
+
+Present the **full proposed JSON** to the user, then ask 3–5 targeted questions tied to what was detected. Do not write yet.
+
+Standard questions (skip those that don't apply):
+
+1. **`git push`** — allow autonomously, or keep asking? Default recommendation: **ask** (irreversible, affects remote).
+2. **Package install** (`npm install`, `pip install`, `cargo add`, etc.) — allow autonomously, or ask? Default recommendation: **ask** (mutates lockfile, pulls supply chain).
+3. **`docker:*`** (if Dockerfile detected) — allow, ask, or deny?
+4. **`WebFetch`** — currently denied. Need it for fetching external docs? Default recommendation: **keep denied**, agent should ask explicitly when needed.
+5. **Anything project-specific** — extra CLIs (`terraform`, `kubectl`, `aws`, `gcloud`, custom scripts in `./bin/`)?
+
+Apply answers to the config and show the final version once more.
+
+### Step 5 — Write the config (only after explicit approval)
+
+Wait for unambiguous user approval ("yes", "ok, write", "go").
+
+Then merge with any existing `.claude/settings.json`:
+
+- **Preserve** all top-level keys other than `permissions` (e.g., `env`, `hooks`, `model`, `statusLine`).
+- **Replace** the `permissions` block with the new merged result.
+- Use Edit (if file exists) or Write (if not) — never shell redirection.
+
+**Do not touch `.claude/settings.local.json`** — that is the user's personal, gitignored layer.
+
+### Step 6 — Verify and explain
+
+Show the final file content and explain in 4–5 lines:
+
+1. Default mode is `acceptEdits` → file edits in the repo run without prompting.
+2. Off-workspace paths (`~`, `/etc`, `.ssh`, etc.) are now **auto-denied** — the agent will not interrupt to ask.
+3. `WebFetch`/`WebSearch` are denied → agent won't try to leave the repo for info unless user explicitly relaxes the rule.
+4. Suggest one quick smoke test: ask the agent to read `~/.ssh/known_hosts`, confirm it gets denied without prompting.
+5. Mention `Shift+Tab` switches modes if user wants to temporarily relax for one task.
+
+## Honest limits
+
+Bash cannot be perfectly sandboxed via deny patterns alone — an agent can use `bash -c "..."`, `eval`, command substitution, environment manipulation. The patterns block the obvious, common escape paths (`curl`, `cd ..`, `sudo`), which is enough for ~95% of real-world risk. For genuine sandbox guarantees, mention these as follow-ups (do not implement here):
+
+- Run Claude Code inside a **devcontainer** (https://code.claude.com/docs/en/devcontainer).
+- Add a **PreToolUse hook** that parses every Bash command and rejects cwd escapes.
+
+## Anti-patterns — never do these
+
+- Do not overwrite `.claude/settings.json` — always merge other sections.
+- Do not write before explicit user approval in Step 5.
+- Do not allow-list `Bash(curl:*)`, `Bash(wget:*)`, broad `Bash(*)`, or `Bash(sudo:*)`.
+- Do not put deny rules in `.claude/settings.local.json` — security policy belongs in the committed `settings.json` so the whole team inherits it.
+- Do not delete the user's existing `settings.local.json` allow rules — they may have been hand-tuned for personal workflows.
+- Do not skip Step 4 questions — the difference between "agent can `git push` at 3am" and "agent asks first" matters and is project-specific.