llm-wb 0.1.0-beta.0

package/scripts/00.chat/git/cleanup-empty-chat-branches/script.sh

@@ -0,0 +1,243 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# agentic-artifact:
+#   schema: agentic-artifact/v2
+#   id: chat.script.git.cleanup-empty-chat-branches
+#   version: 1
+#   status: active
+#   layer: 00.chat
+#   domain: git
+#   disciplines:
+#   - agentic
+#   kind: script
+#   purpose: Delete empty chat branches and matching empty session logs after dry-run
+#     inspection.
+#   portability:
+#     class: required
+#     targets:
+#     - llm-workbench
+#   used_by:
+#   - id: chat.workflows.chat-cleanup
+#     path: .agentic/00.chat/workflows/chat-cleanup.md
+#   - id: harness.architecture.adr.0017-organize-scripts-by-owner-domain-and-capability
+#   - id: chat.script.startup.start-chat-session
+#     path: scripts/00.chat/startup/start-chat-session/script.sh
+#   effects:
+#   - branches
+#   - destructive
+#   - writes-files
+
+# shellcheck source=../../session-log/paths/lib.sh
+source "scripts/00.chat/session-log/paths/lib.sh"
+
+MODE="dry-run"
+BASE_BRANCH=""
+
+usage() {
+  cat <<'EOF'
+Usage: cleanup-empty-chat-branches.sh [--dry-run|--apply] [--base <branch>]
+
+Deletes empty chat branches and their matching empty commitLogs directories.
+
+Safety:
+- Dry-run is the default.
+- --apply is required to delete branches or commitLogs.
+- The current branch is never deleted.
+- Branches checked out in any worktree are never deleted by this script.
+- Only chat/* branches are considered.
+- A branch is empty when it has no commits beyond the base branch.
+- commitLogs/<yyyy>/<mmm>/<dd>/<session> or legacy commitLogs/<session> is
+  deleted only when it names the same branch and has no recorded commits or
+  retention marker.
+EOF
+}
+
+log_names_branch() {
+  local log_file="$1"
+  local branch="$2"
+  local metadata
+
+  metadata="$(sed -n '/<!-- agentic-session/,/-->/p' "$log_file")"
+
+  if [ -n "$metadata" ]; then
+    printf '%s\n' "$metadata" | grep -Fxq "branch: ${branch}"
+    return
+  fi
+
+  grep -Fxq "\`${branch}\`" "$log_file"
+}
+
+log_has_recorded_commit() {
+  local log_file="$1"
+
+  if sed -n '/<!-- agentic-session/,/-->/s/^latest_commit_sha: //p' "$log_file" \
+    | grep -Eq '[^[:space:]]'; then
+    return 0
+  fi
+
+  awk '
+    $0 == "## Commits" {
+      in_section = 1
+      next
+    }
+    in_section && /^## / {
+      exit
+    }
+    in_section && /^- Commit: `[^`]+`/ {
+      found = 1
+    }
+    in_section && /^Commit: `[^`]+`/ {
+      found = 1
+    }
+    END {
+      exit found ? 0 : 1
+    }
+  ' "$log_file"
+}
+
+log_has_retention_marker() {
+  local log_file="$1"
+
+  grep -Eiq \
+    '^(saved|retain|retained|preserve|preserved|keep|kept): +(yes|true)$|agentic-(save|saved|retain|retained|preserve|preserved|keep|kept)-log' \
+    "$log_file"
+}
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --dry-run)
+      MODE="dry-run"
+      shift
+      ;;
+    --apply)
+      MODE="apply"
+      shift
+      ;;
+    --base)
+      if [ $# -lt 2 ] || [ -z "${2:-}" ]; then
+        echo "ERROR: --base requires a branch name." >&2
+        exit 2
+      fi
+      BASE_BRANCH="$2"
+      shift 2
+      ;;
+    --help|-h)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "ERROR: unknown argument: $1" >&2
+      usage >&2
+      exit 2
+      ;;
+  esac
+done
+
+current_branch="$(git branch --show-current)"
+
+if [ -z "$current_branch" ]; then
+  echo "ERROR: current HEAD is detached; refusing cleanup." >&2
+  exit 1
+fi
+
+if [ -z "$BASE_BRANCH" ]; then
+  if git show-ref --verify --quiet refs/heads/main; then
+    BASE_BRANCH="main"
+  elif git show-ref --verify --quiet refs/heads/master; then
+    BASE_BRANCH="master"
+  else
+    echo "ERROR: could not infer base branch. Pass --base <branch>." >&2
+    exit 1
+  fi
+fi
+
+if ! git rev-parse --verify --quiet "$BASE_BRANCH" >/dev/null; then
+  echo "ERROR: base branch does not exist: $BASE_BRANCH" >&2
+  exit 1
+fi
+
+deleted_count=0
+skipped_count=0
+
+echo "Mode: $MODE"
+echo "Base branch: $BASE_BRANCH"
+echo "Current branch: $current_branch"
+
+while IFS= read -r branch; do
+  case "$branch" in
+    chat/*)
+      ;;
+    *)
+      continue
+      ;;
+  esac
+
+  if [ "$branch" = "$current_branch" ]; then
+    echo "SKIP current branch: $branch"
+    skipped_count=$((skipped_count + 1))
+    continue
+  fi
+
+  if git worktree list --porcelain \
+    | awk -v branch="refs/heads/${branch}" '/^branch / && substr($0, 8) == branch { found = 1 } END { exit found ? 0 : 1 }'; then
+    echo "SKIP checked-out worktree branch: $branch"
+    skipped_count=$((skipped_count + 1))
+    continue
+  fi
+
+  ahead_count="$(git rev-list --count "${BASE_BRANCH}..${branch}")"
+  if [ "$ahead_count" != "0" ]; then
+    echo "SKIP non-empty branch: $branch ($ahead_count commits ahead of $BASE_BRANCH)"
+    skipped_count=$((skipped_count + 1))
+    continue
+  fi
+
+  session="${branch#chat/}"
+  log_dir="$(chat_log_dir_for_session "$session")"
+  log_file="${log_dir}/README.md"
+  delete_log="no"
+  keep_log_reason=""
+
+  if [ -f "$log_file" ]; then
+    if log_names_branch "$log_file" "$branch"; then
+      if log_has_recorded_commit "$log_file"; then
+        keep_log_reason="recorded commits"
+      elif log_has_retention_marker "$log_file"; then
+        keep_log_reason="retention marker"
+      else
+        delete_log="yes"
+      fi
+    else
+      echo "WARN log branch mismatch, leaving log in place: $log_dir"
+    fi
+  elif [ -e "$log_dir" ]; then
+    echo "WARN commit log path exists without README, leaving in place: $log_dir"
+  fi
+
+  if [ "$MODE" = "dry-run" ]; then
+    echo "DRY-RUN delete branch: $branch"
+    if [ "$delete_log" = "yes" ]; then
+      echo "DRY-RUN delete log: $log_dir"
+    elif [ -n "$keep_log_reason" ]; then
+      echo "DRY-RUN keep log (${keep_log_reason}): $log_dir"
+    fi
+  else
+    git branch -D "$branch"
+    if [ "$delete_log" = "yes" ]; then
+      git rm -r --ignore-unmatch "$log_dir" >/dev/null
+      rm -rf "$log_dir"
+    fi
+    echo "Deleted empty branch: $branch"
+    if [ "$delete_log" = "yes" ]; then
+      echo "Deleted matching log: $log_dir"
+    elif [ -n "$keep_log_reason" ]; then
+      echo "Kept matching log (${keep_log_reason}): $log_dir"
+    fi
+  fi
+
+  deleted_count=$((deleted_count + 1))
+done < <(git branch --format='%(refname:short)')
+
+echo "Empty chat branches found: $deleted_count"
+echo "Branches skipped: $skipped_count"

package/scripts/00.chat/git/cleanup-empty-chat-branches/smoke-test.sh

@@ -0,0 +1,136 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# agentic-artifact:
+#   schema: agentic-artifact/v2
+#   id: chat.script.git.cleanup-empty-chat-branches.smoke-test
+#   version: 1
+#   status: active
+#   layer: 00.chat
+#   domain: git
+#   disciplines:
+#   - agentic
+#   kind: script
+#   purpose: Smoke test empty chat branch and session log cleanup safety.
+#   portability:
+#     class: reusable
+#     targets:
+#     - llm-workbench
+#   used_by:
+#   - id: chat.workflows.chat-cleanup
+#     path: .agentic/00.chat/workflows/chat-cleanup.md
+#   - id: harness.architecture.adr.0017-organize-scripts-by-owner-domain-and-capability
+#   effects:
+#   - branches
+#   - commits
+#   - destructive
+#   - writes-files
+
+SOURCE_ROOT="$(git rev-parse --show-toplevel)"
+TMP_ROOT="$(mktemp -d "${TMPDIR:-/tmp}/cleanup-empty-chat-branches-smoke.XXXXXX")"
+
+cleanup() {
+  rm -rf "$TMP_ROOT"
+}
+
+trap cleanup EXIT
+
+fail() {
+  echo "ERROR: $*" >&2
+  exit 1
+}
+
+REPO="$TMP_ROOT/repo"
+ mkdir -p "$REPO/scripts/00.chat/git/cleanup-empty-chat-branches" "$REPO/scripts/00.chat/session-log/paths"
+cp "$SOURCE_ROOT/scripts/00.chat/git/cleanup-empty-chat-branches/script.sh" "$REPO/scripts/00.chat/git/cleanup-empty-chat-branches/script.sh"
+cp "$SOURCE_ROOT/scripts/00.chat/session-log/paths/lib.sh" "$REPO/scripts/00.chat/session-log/paths/lib.sh"
+
+git -C "$REPO" init -q -b main
+git -C "$REPO" config user.name "Smoke Test"
+git -C "$REPO" config user.email "smoke@example.invalid"
+
+printf 'base\n' > "$REPO/base.txt"
+git -C "$REPO" add base.txt scripts/00.chat/git/cleanup-empty-chat-branches/script.sh scripts/00.chat/session-log/paths/lib.sh
+git -C "$REPO" commit -q -m "initial"
+
+COMMITTED_SESSION="2026-06-16-07-18-committed-log"
+COMMITTED_BRANCH="chat/$COMMITTED_SESSION"
+COMMITTED_LOG="$REPO/commitLogs/2026/jun/16/$COMMITTED_SESSION/README.md"
+
+git -C "$REPO" switch -q -c "$COMMITTED_BRANCH"
+printf 'work\n' > "$REPO/work.txt"
+git -C "$REPO" add work.txt
+git -C "$REPO" commit -q -m "committed chat work"
+COMMITTED_SHA="$(git -C "$REPO" rev-parse --short HEAD)"
+
+git -C "$REPO" switch -q main
+git -C "$REPO" merge -q --ff-only "$COMMITTED_BRANCH"
+
+mkdir -p "$(dirname "$COMMITTED_LOG")"
+cat > "$COMMITTED_LOG" <<EOF
+# Chat Session: committed log
+
+<!-- agentic-session
+id: $COMMITTED_SESSION
+branch: $COMMITTED_BRANCH
+latest_commit_sha: $COMMITTED_SHA
+-->
+
+## Commits
+
+- Commit: \`$COMMITTED_SHA\`
+EOF
+
+EMPTY_SESSION="2026-06-16-07-19-empty-log"
+EMPTY_BRANCH="chat/$EMPTY_SESSION"
+EMPTY_LOG="$REPO/commitLogs/2026/jun/16/$EMPTY_SESSION/README.md"
+
+git -C "$REPO" branch "$EMPTY_BRANCH"
+mkdir -p "$(dirname "$EMPTY_LOG")"
+cat > "$EMPTY_LOG" <<EOF
+# Chat Session: empty log
+
+<!-- agentic-session
+id: $EMPTY_SESSION
+branch: $EMPTY_BRANCH
+latest_commit_sha:
+-->
+
+## Commits
+
+- None recorded yet.
+EOF
+
+git -C "$REPO" add "$COMMITTED_LOG" "$EMPTY_LOG"
+git -C "$REPO" commit -q -m "add chat logs"
+
+(
+  cd "$REPO"
+  bash scripts/00.chat/git/cleanup-empty-chat-branches/script.sh --apply
+) > "$TMP_ROOT/cleanup.out" 2> "$TMP_ROOT/cleanup.err"
+
+if git -C "$REPO" show-ref --verify --quiet "refs/heads/$COMMITTED_BRANCH"; then
+  fail "merged committed branch was not deleted"
+fi
+
+if [ ! -f "$COMMITTED_LOG" ]; then
+  fail "commit log with recorded commit was deleted"
+fi
+
+if git -C "$REPO" show-ref --verify --quiet "refs/heads/$EMPTY_BRANCH"; then
+  fail "empty branch was not deleted"
+fi
+
+if [ -e "$EMPTY_LOG" ]; then
+  fail "empty unsaved commit log was not deleted"
+fi
+
+if ! grep -q "Kept matching log (recorded commits)" "$TMP_ROOT/cleanup.out"; then
+  fail "cleanup did not report keeping the committed log"
+fi
+
+if ! grep -q "Deleted matching log" "$TMP_ROOT/cleanup.out"; then
+  fail "cleanup did not report deleting the empty log"
+fi
+
+echo "cleanup empty chat branches smoke test passed."

package/scripts/00.chat/local-merge/README.md

@@ -0,0 +1,30 @@
+<!-- agentic-artifact:
+  schema: agentic-artifact/v2
+  id: chat.script.local-merge.readme
+  version: 1
+  status: active
+  layer: 00.chat
+  domain: local-merge
+  disciplines:
+  - agentic
+  kind: script-domain-readme
+  purpose: Explain local merge readiness and visibility scripts.
+  portability:
+    class: required
+    targets:
+    - llm-workbench
+  used_by:
+  - id: chat.workflows.chat-promote-to-main
+    path: .agentic/00.chat/workflows/chat-promote-to-main.md
+  - id: chat.script.local-merge.verify-chat-ready-to-merge-local-main.readme
+    path: scripts/00.chat/local-merge/verify-chat-ready-to-merge-local-main/README.md
+-->
+# Local Merge Scripts
+
+Local merge scripts help decide whether chat work can be integrated into local
+`main`. They are local coordination tools, not push tools.
+
+Use this domain when checking whether a chat branch is current with `main`,
+whether related chat branches are active, or whether overlapping chat work
+needs human attention before promotion.
+

package/scripts/00.chat/local-merge/list-active-chat-branches/README.md

@@ -0,0 +1,29 @@
+<!-- agentic-artifact:
+  schema: agentic-artifact/v2
+  id: chat.script.local-merge.list-active-chat-branches.readme
+  version: 1
+  status: active
+  layer: 00.chat
+  domain: local-merge
+  disciplines:
+  - agentic
+  kind: guide
+  purpose: Explain the read-only report that lists active chat branches before local
+    merge decisions.
+  portability:
+    class: required
+    targets:
+    - llm-workbench
+  used_by:
+  - id: chat.script.local-merge.list-active-chat-branches
+    path: scripts/00.chat/local-merge/list-active-chat-branches/script.sh
+-->
+# List Active Chat Branches
+
+This capability answers: which chat branches are active, and how do they relate
+to local `main`?
+
+It prints chat branches, ahead/behind relation to the base branch, and available
+session metadata such as layer, mode, status, and task. It is read-only and is
+useful before choosing whether to refresh, merge, clean up, or inspect a chat
+branch.

package/scripts/00.chat/local-merge/list-active-chat-branches/script.sh

@@ -0,0 +1,109 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# agentic-artifact:
+#   schema: agentic-artifact/v2
+#   id: chat.script.local-merge.list-active-chat-branches
+#   version: 1
+#   status: active
+#   layer: 00.chat
+#   domain: local-merge
+#   disciplines:
+#   - agentic
+#   kind: script
+#   purpose: List active chat branches with session metadata and relation to local main.
+#   portability:
+#     class: required
+#     targets:
+#     - llm-workbench
+#   used_by:
+#   - id: chat.workflows.chat-refresh-from-main
+#     path: .agentic/00.chat/workflows/chat-refresh-from-main.md
+#   - id: harness.script.run-governed-script
+#     path: scripts/01.harness/run-governed-script.sh
+#   effects:
+#   - read-only
+
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+REPO_ROOT="$(cd "$REPO_ROOT" && pwd -P)"
+
+# shellcheck source=../../session-log/paths/lib.sh
+source "$REPO_ROOT/scripts/00.chat/session-log/paths/lib.sh"
+
+BASE_BRANCH="${1:-main}"
+
+if ! git show-ref --verify --quiet "refs/heads/${BASE_BRANCH}"; then
+  echo "ERROR: base branch does not exist: ${BASE_BRANCH}" >&2
+  exit 1
+fi
+
+current_branch="$(git branch --show-current)"
+tmp_dir="$(mktemp -d)"
+
+cleanup() {
+  rm -rf "$tmp_dir"
+}
+
+trap cleanup EXIT
+
+if [ -z "$current_branch" ]; then
+  echo "ERROR: current HEAD is detached." >&2
+  exit 1
+fi
+
+printf '%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\n' \
+  "branch" "relation" "behind" "ahead" "layer" "mode" "status" "task"
+
+git branch --format='%(refname:short)' | while IFS= read -r branch; do
+  case "$branch" in
+    chat/*)
+      ;;
+    *)
+      continue
+      ;;
+  esac
+
+  session_id="${branch#chat/}"
+  log_file="$(chat_log_file_for_session "$session_id")"
+  branch_log_file="${tmp_dir}/$(printf '%s\n' "$session_id" | tr -c 'A-Za-z0-9._-' '_').README.md"
+
+  if [ -f "$log_file" ]; then
+    layer="$(chat_log_metadata_value "$log_file" "layer")"
+    mode="$(chat_log_metadata_value "$log_file" "mode")"
+    status="$(chat_log_metadata_value "$log_file" "status")"
+    task="$(chat_log_metadata_value "$log_file" "task")"
+  elif git cat-file -e "${branch}:commitLogs/${session_id}/README.md" 2>/dev/null; then
+    git show "${branch}:commitLogs/${session_id}/README.md" > "$branch_log_file"
+    layer="$(chat_log_metadata_value "$branch_log_file" "layer")"
+    mode="$(chat_log_metadata_value "$branch_log_file" "mode")"
+    status="$(chat_log_metadata_value "$branch_log_file" "status")"
+    task="$(chat_log_metadata_value "$branch_log_file" "task")"
+  else
+    layer="missing-log"
+    mode="missing-log"
+    status="missing-log"
+    task="missing session log: ${log_file}"
+  fi
+
+  counts="$(git rev-list --left-right --count "${BASE_BRANCH}...${branch}")"
+  behind="${counts%%	*}"
+  ahead="${counts##*	}"
+
+  if [ "$behind" = "0" ] && [ "$ahead" = "0" ]; then
+    relation="even"
+  elif [ "$behind" = "0" ]; then
+    relation="ahead"
+  elif [ "$ahead" = "0" ]; then
+    relation="behind"
+  else
+    relation="diverged"
+  fi
+
+  if [ "$branch" = "$current_branch" ]; then
+    branch="${branch}*"
+  fi
+
+  printf '%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\n' \
+    "$branch" "$relation" "$behind" "$ahead" \
+    "${layer:-unknown}" "${mode:-unknown}" "${status:-unknown}" "${task:-}"
+done

package/scripts/00.chat/local-merge/report-chat-branch-overlaps/README.md

@@ -0,0 +1,29 @@
+<!-- agentic-artifact:
+  schema: agentic-artifact/v2
+  id: chat.script.local-merge.report-chat-branch-overlaps.readme
+  version: 1
+  status: active
+  layer: 00.chat
+  domain: local-merge
+  disciplines:
+  - agentic
+  kind: guide
+  purpose: Explain the read-only report that finds changed-path overlap between chat
+    branches.
+  portability:
+    class: required
+    targets:
+    - llm-workbench
+  used_by:
+  - id: chat.script.local-merge.report-chat-branch-overlaps
+    path: scripts/00.chat/local-merge/report-chat-branch-overlaps/script.sh
+-->
+# Report Chat Branch Overlaps
+
+This capability answers: which chat branches or active worktree changes touch
+the same files?
+
+It builds changed-path sets for local chat branches relative to a base branch,
+adds the current worktree's unstaged, staged, and untracked paths, and reports
+overlaps between those sets. It is read-only and helps identify merge risk
+before refresh or local merge work.