llm-wb 0.1.0-beta.0

package/scripts/00.chat/worktree/check-write-location/script.sh

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# agentic-artifact:
+#   schema: agentic-artifact/v2
+#   id: chat.script.worktree.check-write-location
+#   version: 1
+#   status: active
+#   layer: 00.chat
+#   domain: worktree
+#   disciplines:
+#   - agentic
+#   kind: script
+#   purpose: Enforce task writes from chat-owned worktrees instead of the root integration
+#     worktree.
+#   portability:
+#     class: required
+#     targets:
+#     - llm-workbench
+#   used_by:
+#   - id: chat.script.worktree.check-write-location.readme
+#     path: scripts/00.chat/worktree/check-write-location/README.md
+#   effects:
+#   - read-only
+usage() {
+  cat <<'EOF'
+Usage:
+  check-write-location.sh [--allow-root-maintenance]
+
+Fails when task writes would run from the root integration worktree. Chat task
+work must run from that chat branch's canonical chat-owned worktree.
+
+Set AGENTIC_ALLOW_ROOT_WRITE=1 only for explicit root maintenance operations.
+EOF
+}
+
+ALLOW_ROOT_MAINTENANCE="no"
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --allow-root-maintenance)
+      ALLOW_ROOT_MAINTENANCE="yes"
+      shift
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      usage >&2
+      exit 2
+      ;;
+  esac
+done
+
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+REPO_ROOT="$(cd "$REPO_ROOT" && pwd -P)"
+
+# shellcheck source=../paths/lib.sh
+source "$REPO_ROOT/scripts/00.chat/worktree/paths/lib.sh"
+
+PRIMARY_PATH="$(chat_worktree_primary_path)"
+PRIMARY_PATH="$(cd "$PRIMARY_PATH" && pwd -P)"
+BRANCH="$(git -C "$REPO_ROOT" branch --show-current)"
+
+if [ "$REPO_ROOT" = "$PRIMARY_PATH" ]; then
+  if [ "${AGENTIC_ALLOW_ROOT_WRITE:-}" = "1" ] || [ "$ALLOW_ROOT_MAINTENANCE" = "yes" ]; then
+    echo "root-maintenance-allowed"
+    exit 0
+  fi
+
+  echo "ERROR: refusing task write in root integration worktree: $REPO_ROOT" >&2
+  echo "Use the chat-owned worktree for chat work." >&2
+  exit 1
+fi
+
+case "$BRANCH" in
+  chat/*) ;;
+  *)
+    echo "ERROR: current worktree is not on a chat branch: $BRANCH" >&2
+    exit 1
+    ;;
+esac
+
+EXPECTED_PATH="$(chat_worktree_path_for_branch "$PRIMARY_PATH" "$BRANCH")"
+EXPECTED_PATH="$(cd "$EXPECTED_PATH" 2>/dev/null && pwd -P || printf '%s\n' "$EXPECTED_PATH")"
+
+if [ "$REPO_ROOT" != "$EXPECTED_PATH" ]; then
+  echo "ERROR: current chat branch is not in its canonical chat worktree." >&2
+  echo "Current:  $REPO_ROOT" >&2
+  echo "Expected: $EXPECTED_PATH" >&2
+  exit 1
+fi
+
+echo "chat-worktree"

package/scripts/00.chat/worktree/dirty-worktree-check/README.md

@@ -0,0 +1,77 @@
+<!-- agentic-artifact:
+  schema: agentic-artifact/v2
+  id: chat.script.worktree.dirty-worktree-check.readme
+  version: 1
+  status: active
+  layer: 00.chat
+  domain: worktree
+  disciplines:
+  - agentic
+  kind: capability-readme
+  purpose: Explain clean, dirty, and session-bookkeeping-only worktree checks.
+  portability:
+    class: required
+    targets:
+    - llm-workbench
+  used_by:
+  - id: chat.script.worktree.dirty-worktree-check
+    path: scripts/00.chat/worktree/dirty-worktree-check/script.sh
+  - id: harness.architecture.adr.0017-organize-scripts-by-owner-domain-and-capability
+-->
+# Dirty Worktree Check
+
+`script.sh` reports whether the current worktree is clean enough for the next
+governed step.
+
+It is intentionally small: it answers one question before startup, refresh,
+commit, or promotion workflows continue.
+
+## Modes
+
+Default mode:
+
+```bash
+bash scripts/00.chat/worktree/dirty-worktree-check/script.sh
+```
+
+Outputs:
+
+- `clean` and exits `0` when there are no Git changes
+- `dirty` and exits non-zero when any tracked, staged, or untracked file is
+  dirty
+
+Session-bookkeeping mode:
+
+```bash
+bash scripts/00.chat/worktree/dirty-worktree-check/script.sh --allow-session-bookkeeping
+```
+
+This mode allows dirt only when all dirty paths are the current chat session log.
+It prints `bookkeeping-only` and exits `0` in that case.
+
+## Mental Model
+
+Dirty state is not always bad. Sometimes the only dirty file is the session log
+after a task commit has been recorded. That is expected bookkeeping and can be
+checkpointed separately.
+
+Other dirty state is ambiguous. This helper stops workflows before they
+accidentally continue across unreviewed or unrelated changes.
+
+## What This Does Not Do
+
+- It does not clean the worktree.
+- It does not stage files.
+- It does not commit session bookkeeping.
+- It does not decide whether unrelated dirt is safe.
+- It does not inspect file contents beyond identifying dirty paths.
+
+## Compatibility
+
+The old shared path remains available:
+
+```bash
+scripts/00.chat/worktree/dirty-worktree-check/script.sh
+```
+
+That file is now a compatibility wrapper around the canonical implementation.

package/scripts/00.chat/worktree/dirty-worktree-check/script.sh

@@ -0,0 +1,93 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# agentic-artifact:
+#   schema: agentic-artifact/v2
+#   id: chat.script.worktree.dirty-worktree-check
+#   version: 1
+#   status: active
+#   layer: 00.chat
+#   domain: worktree
+#   disciplines:
+#   - agentic
+#   kind: script
+#   purpose: Check worktree cleanliness with optional current-session bookkeeping tolerance.
+#   portability:
+#     class: required
+#     targets:
+#     - llm-workbench
+#   used_by:
+#   - id: chat.script.worktree.dirty-worktree-check.readme
+#     path: scripts/00.chat/worktree/dirty-worktree-check/README.md
+#   effects:
+#   - read-only
+usage() {
+  cat <<'EOF'
+Usage:
+  dirty-worktree-check.sh [--allow-session-bookkeeping]
+
+Checks whether the worktree is clean. With --allow-session-bookkeeping, changes
+limited to the current chat session log are accepted.
+EOF
+}
+
+ALLOW_SESSION_BOOKKEEPING="no"
+
+if [ $# -gt 1 ]; then
+  usage >&2
+  exit 2
+fi
+
+if [ $# -eq 1 ]; then
+  case "$1" in
+    --allow-session-bookkeeping)
+      ALLOW_SESSION_BOOKKEEPING="yes"
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      usage >&2
+      exit 2
+      ;;
+  esac
+fi
+
+if [[ -z "$(git status --porcelain)" ]]; then
+  echo "clean"
+  exit 0
+fi
+
+if [ "$ALLOW_SESSION_BOOKKEEPING" = "yes" ]; then
+  # shellcheck source=../../session-log/paths/lib.sh
+  source "scripts/00.chat/session-log/paths/lib.sh"
+
+  BRANCH="$(git branch --show-current)"
+
+  if SESSION_ID="$(chat_session_id_from_branch "$BRANCH")"; then
+    LOG_FILE="$(chat_log_file_for_session "$SESSION_ID")"
+    MIXED_FILES="$(
+      {
+        git diff --name-only
+        git diff --cached --name-only
+        git ls-files --others --exclude-standard
+      } | awk \
+        -v log_file="$LOG_FILE" \
+        '$0 != "" && $0 != log_file' \
+        | sort -u
+    )"
+
+    if [ -z "${MIXED_FILES// }" ]; then
+      echo "bookkeeping-only"
+      exit 0
+    fi
+  fi
+fi
+
+if [[ -n "$(git status --porcelain)" ]]; then
+  echo "dirty"
+  exit 1
+fi
+
+echo "clean"

package/scripts/00.chat/worktree/ensure-chat-worktree/README.md

@@ -0,0 +1,33 @@
+<!-- agentic-artifact:
+  schema: agentic-artifact/v2
+  id: chat.script.worktree.ensure-chat-worktree.readme
+  version: 1
+  status: active
+  layer: 00.chat
+  domain: worktree
+  disciplines:
+  - agentic
+  kind: capability-readme
+  purpose: Explain creating or verifying the chat-owned worktree for a session.
+  portability:
+    class: required
+    targets:
+    - llm-workbench
+  used_by:
+  - id: chat.script.startup.start-chat-session
+    path: scripts/00.chat/startup/start-chat-session/script.sh
+  - id: chat.script.worktree.ensure-chat-worktree
+    path: scripts/00.chat/worktree/ensure-chat-worktree/script.sh
+-->
+# Ensure Chat Worktree
+
+`script.sh` creates or verifies the canonical worktree for the chat branch named
+in a session log.
+
+Startup uses this so the session branch has a separate physical checkout for
+task work. If the worktree already exists, the script verifies that it belongs
+to the same repository and is on the expected branch.
+
+The script prints the worktree path. It does not stage task files, commit, merge,
+push, or clean existing work.
+

package/scripts/00.chat/worktree/ensure-chat-worktree/script.sh

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# agentic-artifact:
+#   schema: agentic-artifact/v2
+#   id: chat.script.worktree.ensure-chat-worktree
+#   version: 1
+#   status: active
+#   layer: 00.chat
+#   domain: worktree
+#   disciplines:
+#   - agentic
+#   kind: script
+#   purpose: Create or verify the chat-owned worktree for a session branch.
+#   portability:
+#     class: required
+#     targets:
+#     - llm-workbench
+#   used_by:
+#   - id: chat.workflows.chat-start
+#     path: .agentic/00.chat/workflows/chat-start.md
+#   - id: chat.script.startup.start-chat-session
+#     path: scripts/00.chat/startup/start-chat-session/script.sh
+#   effects:
+#   - worktrees
+usage() {
+  cat <<'EOF'
+Usage:
+  ensure-chat-worktree.sh <session-log>
+
+Creates or verifies the canonical chat-owned worktree for the chat branch named
+in a session log. The root worktree is an integration console; task work should
+happen in the returned chat worktree path.
+EOF
+}
+
+if [ $# -ne 1 ] || [ "${1:-}" = "--help" ] || [ "${1:-}" = "-h" ]; then
+  usage >&2
+  exit 2
+fi
+
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+REPO_ROOT="$(cd "$REPO_ROOT" && pwd -P)"
+
+# shellcheck source=../paths/lib.sh
+source "$REPO_ROOT/scripts/00.chat/worktree/paths/lib.sh"
+
+SESSION_LOG="$1"
+case "$SESSION_LOG" in
+  /*) ;;
+  *) SESSION_LOG="$REPO_ROOT/$SESSION_LOG" ;;
+esac
+
+if [ ! -f "$SESSION_LOG" ]; then
+  echo "ERROR: missing chat session log: $SESSION_LOG" >&2
+  exit 1
+fi
+
+BRANCH="$(chat_worktree_metadata_value "$SESSION_LOG" "branch")"
+if [ -z "${BRANCH// }" ]; then
+  echo "ERROR: session log is missing branch metadata: $SESSION_LOG" >&2
+  exit 1
+fi
+
+case "$BRANCH" in
+  chat/*) ;;
+  *)
+    echo "ERROR: session branch is not a chat branch: $BRANCH" >&2
+    exit 1
+    ;;
+esac
+
+if ! git -C "$REPO_ROOT" show-ref --verify --quiet "refs/heads/${BRANCH}"; then
+  echo "ERROR: session branch does not exist locally: $BRANCH" >&2
+  exit 1
+fi
+
+WORKTREE_PATH="$(chat_worktree_path_for_branch "$REPO_ROOT" "$BRANCH")"
+WORKTREE_ROOT="${WORKTREE_PATH%/*}"
+PRIMARY_PATH="$(chat_worktree_primary_path)"
+PRIMARY_PATH="$(cd "$PRIMARY_PATH" && pwd -P)"
+
+branch_worktrees="$(
+  git -C "$REPO_ROOT" worktree list --porcelain \
+    | awk -v branch="refs/heads/${BRANCH}" '
+      /^worktree / { path = substr($0, 10) }
+      /^branch / && substr($0, 8) == branch { print path }
+    '
+)"
+
+while IFS= read -r branch_worktree; do
+  if [ -z "${branch_worktree// }" ]; then
+    continue
+  fi
+
+  branch_worktree="$(cd "$branch_worktree" && pwd -P)"
+
+  if [ "$branch_worktree" = "$WORKTREE_PATH" ]; then
+    continue
+  fi
+
+  if [ "$branch_worktree" = "$PRIMARY_PATH" ]; then
+    echo "ERROR: session branch is checked out in the root integration worktree:" >&2
+    echo "$branch_worktree" >&2
+    echo "Switch the root worktree away from the chat branch before creating the chat-owned worktree." >&2
+    exit 1
+  fi
+
+  echo "ERROR: session branch is already checked out in another worktree:" >&2
+  echo "$branch_worktree" >&2
+  echo "Expected chat-owned worktree:" >&2
+  echo "$WORKTREE_PATH" >&2
+  exit 1
+done <<< "$branch_worktrees"
+
+if [ -e "$WORKTREE_PATH" ]; then
+  if ! git -C "$WORKTREE_PATH" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    echo "ERROR: chat worktree path exists but is not a git worktree: $WORKTREE_PATH" >&2
+    exit 1
+  fi
+
+  current_branch="$(git -C "$WORKTREE_PATH" branch --show-current)"
+  if [ "$current_branch" != "$BRANCH" ]; then
+    echo "ERROR: chat worktree is on '$current_branch', expected '$BRANCH': $WORKTREE_PATH" >&2
+    exit 1
+  fi
+else
+  mkdir -p "$WORKTREE_ROOT"
+  git -C "$REPO_ROOT" worktree add --quiet "$WORKTREE_PATH" "$BRANCH"
+fi
+
+printf '%s\n' "$WORKTREE_PATH"

package/scripts/00.chat/worktree/open-window/README.md

@@ -0,0 +1,34 @@
+<!-- agentic-artifact:
+  schema: agentic-artifact/v2
+  id: chat.script.worktree.open-window.readme
+  version: 1
+  status: active
+  layer: 00.chat
+  domain: worktree
+  disciplines:
+  - agentic
+  kind: capability-readme
+  purpose: Explain opening a VS Code window for a chat-owned worktree.
+  portability:
+    class: required
+    targets:
+    - llm-workbench
+  used_by:
+  - id: chat.script.worktree.open-window
+    path: scripts/00.chat/worktree/open-window/script.sh
+  - id: chat.script.command.open-window
+    path: scripts/00.chat/command/open-window/script.sh
+-->
+# Open Window Worktree Capability
+
+`script.sh` opens a new VS Code window for a chat-owned worktree.
+
+With no argument, it reads the current chat branch session log and opens the
+`worktree` metadata path. With one argument, it accepts either a worktree path
+or a session-log `README.md` path.
+
+The command is best-effort. If the `code` CLI is unavailable or cannot open the
+window, the script prints a warning and exits successfully so chat startup does
+not fail after branch and worktree creation.
+
+Set `CHAT_OPEN_WORKTREE_WINDOW=skip` to suppress the window open.

package/scripts/00.chat/worktree/open-window/script.sh

@@ -0,0 +1,131 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# agentic-artifact:
+#   schema: agentic-artifact/v2
+#   id: chat.script.worktree.open-window
+#   version: 1
+#   status: active
+#   layer: 00.chat
+#   domain: worktree
+#   disciplines:
+#   - agentic
+#   kind: script
+#   purpose: Open a VS Code window for a chat-owned worktree.
+#   portability:
+#     class: required
+#     targets:
+#     - llm-workbench
+#   used_by:
+#   - id: chat.script.startup.start-chat-session
+#     path: scripts/00.chat/startup/start-chat-session/script.sh
+#   - id: chat.script.command.open-window
+#     path: scripts/00.chat/command/open-window/script.sh
+#   effects:
+#   - read-only
+usage() {
+  cat <<'EOF'
+Usage: open-window [worktree-path|session-log]
+
+Opens the current chat worktree in a new VS Code window. If an argument is
+provided, it may be a worktree path or a session-log README.md path.
+EOF
+}
+
+# shellcheck source=../../session-log/paths/lib.sh
+source "scripts/00.chat/session-log/paths/lib.sh"
+
+target="${1:-}"
+
+if [ "${target:-}" = "-h" ] || [ "${target:-}" = "--help" ]; then
+  usage
+  exit 0
+fi
+
+if [ "$#" -gt 1 ]; then
+  usage >&2
+  exit 2
+fi
+
+resolve_current_worktree() {
+  local branch session_id log_file worktree
+
+  branch="$(git branch --show-current)"
+  if ! session_id="$(chat_session_id_from_branch "$branch")"; then
+    echo "ERROR: current branch is not a chat branch: $branch" >&2
+    echo "Pass a chat worktree path or session log path when running from the root worktree." >&2
+    return 1
+  fi
+
+  log_file="$(chat_log_file_for_session "$session_id")"
+  if [ ! -f "$log_file" ]; then
+    echo "ERROR: missing chat log: $log_file" >&2
+    return 1
+  fi
+
+  worktree="$(chat_log_metadata_value "$log_file" "worktree")"
+  if [ -z "${worktree// }" ]; then
+    echo "ERROR: session log is missing worktree metadata: $log_file" >&2
+    return 1
+  fi
+
+  printf '%s\n' "$worktree"
+}
+
+resolve_target() {
+  local candidate="$1"
+
+  if [ -z "${candidate// }" ]; then
+    resolve_current_worktree
+    return
+  fi
+
+  if [ -f "$candidate" ]; then
+    chat_log_metadata_value "$candidate" "worktree"
+    return
+  fi
+
+  printf '%s\n' "$candidate"
+}
+
+WORKTREE_PATH="$(resolve_target "$target")"
+
+if [ -z "${WORKTREE_PATH// }" ]; then
+  echo "ERROR: could not resolve chat worktree path." >&2
+  exit 1
+fi
+
+if [ ! -d "$WORKTREE_PATH" ]; then
+  echo "ERROR: chat worktree path does not exist: $WORKTREE_PATH" >&2
+  exit 1
+fi
+
+if ! git -C "$WORKTREE_PATH" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  echo "ERROR: path is not a git worktree: $WORKTREE_PATH" >&2
+  exit 1
+fi
+
+case "${CHAT_OPEN_WORKTREE_WINDOW:-open}" in
+  open|"")
+    ;;
+  0|false|no|skip)
+    echo "Skipping VS Code window open: $WORKTREE_PATH"
+    exit 0
+    ;;
+  *)
+    echo "ERROR: invalid CHAT_OPEN_WORKTREE_WINDOW value: ${CHAT_OPEN_WORKTREE_WINDOW}" >&2
+    echo "Use open, skip, 0, false, or no." >&2
+    exit 2
+    ;;
+esac
+
+if ! command -v code >/dev/null 2>&1; then
+  echo "WARNING: VS Code CLI 'code' not found; cannot open chat worktree window: $WORKTREE_PATH" >&2
+  exit 0
+fi
+
+if code --new-window "$WORKTREE_PATH"; then
+  echo "Opened VS Code window: $WORKTREE_PATH"
+else
+  echo "WARNING: VS Code CLI failed to open chat worktree window: $WORKTREE_PATH" >&2
+fi

package/scripts/00.chat/worktree/paths/README.md

@@ -0,0 +1,32 @@
+<!-- agentic-artifact:
+  schema: agentic-artifact/v2
+  id: chat.script.worktree.paths.readme
+  version: 1
+  status: active
+  layer: 00.chat
+  domain: worktree
+  disciplines:
+  - agentic
+  kind: capability-readme
+  purpose: Explain helper functions for chat worktree paths and metadata.
+  portability:
+    class: required
+    targets:
+    - llm-workbench
+  used_by:
+  - id: chat.script.worktree.paths.lib
+    path: scripts/00.chat/worktree/paths/lib.sh
+  - id: chat.script.worktree.ensure-chat-worktree
+    path: scripts/00.chat/worktree/ensure-chat-worktree/script.sh
+-->
+# Worktree Paths
+
+`lib.sh` provides shell helper functions for deriving canonical chat worktree
+paths.
+
+The helpers make worktree paths deterministic from the repository root and chat
+branch name. That lets startup, reporting, recovery, and verification agree on
+where a chat-owned worktree should live.
+
+This library is read-only. It does not create worktrees or change branches.
+

package/scripts/00.chat/worktree/paths/lib.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+
+# agentic-artifact:
+#   schema: agentic-artifact/v2
+#   id: chat.script.worktree.paths.lib
+#   version: 1
+#   status: active
+#   layer: 00.chat
+#   domain: worktree
+#   disciplines:
+#   - agentic
+#   kind: script
+#   purpose: Provide canonical chat worktree path and metadata helper functions.
+#   portability:
+#     class: required
+#     targets:
+#     - llm-workbench
+#   used_by:
+#   - id: chat.script.reporting.report-chat-workspaces
+#     path: scripts/00.chat/reporting/report-chat-workspaces/script.sh
+#   - id: chat.script.startup.start-chat-session
+#     path: scripts/00.chat/startup/start-chat-session/script.sh
+#   - id: chat.script.worktree.ensure-chat-worktree
+#     path: scripts/00.chat/worktree/ensure-chat-worktree/script.sh
+#   effects:
+#   - read-only
+chat_worktree_repo_root() {
+  local repo_root
+
+  repo_root="$(git rev-parse --show-toplevel)"
+  cd "$repo_root" && pwd -P
+}
+
+chat_worktree_repo_key() {
+  local repo_root="$1"
+
+  printf '%s' "$repo_root" | cksum | awk '{print $1}'
+}
+
+chat_worktree_safe_name() {
+  printf '%s' "$1" | sed 's#[^A-Za-z0-9._-]#_#g'
+}
+
+chat_worktree_root_for_repo() {
+  local repo_root="$1"
+  local repo_slug
+
+  repo_slug="$(chat_worktree_safe_name "$(basename "$repo_root")")"
+  printf '%s\n' "${AGENTIC_CHAT_WORKTREE_ROOT:-${TMPDIR:-/tmp}/agentic-chat-worktrees/${repo_slug}-$(chat_worktree_repo_key "$repo_root")}"
+}
+
+chat_worktree_path_for_branch() {
+  local repo_root="$1"
+  local branch="$2"
+  local branch_slug branch_key
+
+  branch_slug="$(chat_worktree_safe_name "$branch")"
+  branch_key="$(printf '%s' "$branch" | cksum | awk '{print $1}')"
+  printf '%s/%s-%s\n' "$(chat_worktree_root_for_repo "$repo_root")" "$branch_slug" "$branch_key"
+}
+
+chat_worktree_primary_path() {
+  git worktree list --porcelain | sed -n '1s/^worktree //p'
+}
+
+chat_worktree_metadata_value() {
+  local log_file="$1"
+  local key="$2"
+
+  sed -n "/<!-- agentic-session/,/-->/s/^${key}: //p" "$log_file" | head -n 1
+}