llm-wb 0.1.0-beta.0

package/scripts/00.chat/startup/start-chat-session/smoke-test.sh

@@ -0,0 +1,182 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# agentic-artifact:
+#   schema: agentic-artifact/v2
+#   id: chat.script.startup.start-chat-session.smoke-test
+#   version: 1
+#   status: active
+#   layer: 00.chat
+#   domain: startup
+#   disciplines:
+#   - agentic
+#   kind: script
+#   purpose: Smoke test chat startup creates a separate chat-owned worktree.
+#   portability:
+#     class: reusable
+#     targets:
+#     - llm-workbench
+#   used_by:
+#   - id: chat.workflows.chat-start
+#     path: .agentic/00.chat/workflows/chat-start.md
+#   - id: chat.workflows.bootstrap-chat-workbench-repo
+#     path: .agentic/00.chat/workflows/bootstrap-chat-workbench-repo.md
+#   - id: chat.script.startup.start-chat-session.readme
+#     path: scripts/00.chat/startup/start-chat-session/README.md
+#   effects:
+#   - writes-files
+#   - branches
+#   - worktrees
+#   - commits
+fail() {
+  echo "FAIL: $*" >&2
+  exit 1
+}
+
+SOURCE_ROOT="$(git rev-parse --show-toplevel)"
+TMP_ROOT="$(mktemp -d "${TMPDIR:-/tmp}/chat-worktree-session-smoke.XXXXXX")"
+
+cleanup() {
+  rm -rf "$TMP_ROOT"
+}
+
+trap cleanup EXIT
+
+REPO="$TMP_ROOT/repo"
+mkdir -p "$REPO"
+git -C "$REPO" init --quiet --initial-branch=main
+
+mkdir -p \
+  "$REPO/scripts/00.chat/git/cleanup-empty-chat-branches" \
+  "$REPO/scripts/00.chat/session-log/paths" \
+  "$REPO/scripts/00.chat/startup/start-chat-session" \
+  "$REPO/scripts/00.chat/worktree/ensure-chat-worktree" \
+  "$REPO/scripts/00.chat/worktree/open-window" \
+  "$REPO/scripts/00.chat/worktree/paths"
+
+cp "$SOURCE_ROOT/scripts/00.chat/session-log/paths/lib.sh" "$REPO/scripts/00.chat/session-log/paths/lib.sh"
+cp "$SOURCE_ROOT/scripts/00.chat/worktree/paths/lib.sh" "$REPO/scripts/00.chat/worktree/paths/lib.sh"
+cp "$SOURCE_ROOT/scripts/00.chat/worktree/ensure-chat-worktree/script.sh" "$REPO/scripts/00.chat/worktree/ensure-chat-worktree/script.sh"
+cp "$SOURCE_ROOT/scripts/00.chat/startup/start-chat-session/script.sh" "$REPO/scripts/00.chat/startup/start-chat-session/script.sh"
+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/worktree/open-window/script.sh" "$REPO/scripts/00.chat/worktree/open-window/script.sh"
+chmod +x "$REPO/scripts/00.chat/startup/start-chat-session/script.sh" "$REPO/scripts/00.chat/worktree/ensure-chat-worktree/script.sh" "$REPO/scripts/00.chat/worktree/open-window/script.sh" "$REPO/scripts/00.chat/git/cleanup-empty-chat-branches/script.sh"
+
+printf 'base\n' > "$REPO/README.md"
+git -C "$REPO" add README.md scripts
+git -C "$REPO" -c user.name='Smoke Test' -c user.email='smoke@example.invalid' commit --quiet -m 'base'
+
+AGENTIC_CHAT_WORKTREE_ROOT="$TMP_ROOT/worktrees" \
+CHAT_CLEANUP_EMPTY_BRANCHES=skip \
+CHAT_COPY_PROMPT=skip \
+  bash -c 'cd "$1" && shift && "$@"' sh "$REPO" \
+    bash scripts/00.chat/startup/start-chat-session/script.sh "test chat worktree session" \
+    >"$TMP_ROOT/chat-worktree-session.out"
+
+if ! grep -q 'Skipping VS Code window open:' "$TMP_ROOT/chat-worktree-session.out"; then
+  fail "startup did not skip VS Code window open by default"
+fi
+
+root_branch="$(git -C "$REPO" branch --show-current)"
+if [ "$root_branch" != "main" ]; then
+  fail "root branch changed to $root_branch"
+fi
+
+chat_branch="$(git -C "$REPO" branch --format='%(refname:short)' | grep '^chat/' | head -n 1)"
+if [ -z "$chat_branch" ]; then
+  fail "chat branch was not created"
+fi
+
+worktree_path="$(
+  git -C "$REPO" worktree list --porcelain \
+    | awk -v branch="refs/heads/${chat_branch}" '
+      /^worktree / { path = substr($0, 10) }
+      /^branch / && substr($0, 8) == branch { print path }
+    '
+)"
+
+if [ -z "$worktree_path" ] || [ "$worktree_path" = "$REPO" ]; then
+  fail "chat branch does not have a separate worktree"
+fi
+
+if [ -n "$(git -C "$REPO" diff --cached --name-only)" ]; then
+  fail "root worktree has staged changes"
+fi
+
+if ! git -C "$worktree_path" diff --cached --name-only | grep -q '^commitLogs/'; then
+  fail "chat worktree did not stage the session log"
+fi
+
+session_log="$(git -C "$worktree_path" diff --cached --name-only | grep '^commitLogs/.*/README.md$' | head -n 1)"
+if [ -z "$session_log" ]; then
+  fail "could not find staged session log"
+fi
+
+layer="$(sed -n '/<!-- agentic-session/,/-->/s/^layer: //p' "$worktree_path/$session_log" | head -n 1)"
+mode="$(sed -n '/<!-- agentic-session/,/-->/s/^mode: //p' "$worktree_path/$session_log" | head -n 1)"
+workflow="$(sed -n '/<!-- agentic-session/,/-->/s/^workflow: //p' "$worktree_path/$session_log" | head -n 1)"
+chat_lifecycle_workflow="$(sed -n '/<!-- agentic-session/,/-->/s/^chat_lifecycle_workflow: //p' "$worktree_path/$session_log" | head -n 1)"
+
+if [ -n "$layer" ] || [ -n "$mode" ] || [ -n "$workflow" ]; then
+  fail "chat startup wrote durable classification fields"
+fi
+
+if [ "$chat_lifecycle_workflow" != ".agentic/00.chat/workflows/chat-start.md" ]; then
+  fail "chat startup did not record the chat lifecycle workflow: ${chat_lifecycle_workflow:-missing}"
+fi
+
+if ! sed -n '/<!-- agentic-session/,/-->/p' "$worktree_path/$session_log" | grep -q '^latest_context_packet_id:$'; then
+  fail "chat startup did not initialize latest_context_packet_id"
+fi
+
+if ! sed -n '/<!-- agentic-session/,/-->/p' "$worktree_path/$session_log" | grep -q '^latest_context_packet_routing_summary:$'; then
+  fail "chat startup did not initialize latest_context_packet_routing_summary"
+fi
+
+FAKE_BIN="$TMP_ROOT/fake-bin"
+mkdir -p "$FAKE_BIN"
+cat > "$FAKE_BIN/clip.exe" <<'EOF'
+#!/usr/bin/env bash
+cat >/dev/null
+exit 1
+EOF
+chmod +x "$FAKE_BIN/clip.exe"
+
+AGENTIC_CHAT_WORKTREE_ROOT="$TMP_ROOT/worktrees" \
+CHAT_CLEANUP_EMPTY_BRANCHES=skip \
+CHAT_COPY_PROMPT=copy \
+CHAT_OPEN_WORKTREE_WINDOW=skip \
+PATH="$FAKE_BIN:$PATH" \
+  bash -c 'cd "$1" && shift && "$@"' sh "$REPO" \
+    bash scripts/00.chat/startup/start-chat-session/script.sh "test clipboard fallback session" \
+    >"$TMP_ROOT/chat-worktree-session-clipboard.out" 2>&1
+
+if ! grep -q 'WARNING: Clipboard copy via clip.exe failed; printing prompt instead.' "$TMP_ROOT/chat-worktree-session-clipboard.out"; then
+  fail "clipboard failure did not warn before falling back"
+fi
+
+if ! grep -q 'Paste this into Codex / Claude / Mistral:' "$TMP_ROOT/chat-worktree-session-clipboard.out"; then
+  fail "clipboard failure did not print the first prompt"
+fi
+
+if ! grep -q 'Governed startup bootstrap has already created this chat branch, worktree, and session log.' "$TMP_ROOT/chat-worktree-session-clipboard.out"; then
+  fail "first prompt did not explain startup bootstrap boundary"
+fi
+
+if ! grep -q 'Default mode after startup bootstrap: read-only until I grant write permission in this chat.' "$TMP_ROOT/chat-worktree-session-clipboard.out"; then
+  fail "first prompt did not preserve task write permission boundary"
+fi
+
+if ! grep -q "For prompt-level routing, use the current user request, this repo's assistant instructions, and any repo-provided context router if one exists." "$TMP_ROOT/chat-worktree-session-clipboard.out"; then
+  fail "first prompt did not explain neutral prompt-level routing"
+fi
+
+if ! grep -q 'Do not assign the whole chat a durable layer, mode, or workflow.' "$TMP_ROOT/chat-worktree-session-clipboard.out"; then
+  fail "first prompt did not preserve durable classification guard"
+fi
+
+if grep -q 'query the RAG/rulebook runtime' "$TMP_ROOT/chat-worktree-session-clipboard.out"; then
+  fail "first prompt assumes a RAG/rulebook runtime exists"
+fi
+
+echo "chat worktree session smoke test passed."

package/scripts/00.chat/startup/start-new-chat/README.md

@@ -0,0 +1,31 @@
+<!-- agentic-artifact:
+  schema: agentic-artifact/v2
+  id: chat.script.startup.start-new-chat.readme
+  version: 1
+  status: active
+  layer: 00.chat
+  domain: startup
+  disciplines:
+  - agentic
+  kind: capability-readme
+  purpose: Explain the new-chat startup wrapper.
+  portability:
+    class: required
+    targets:
+    - llm-workbench
+  used_by:
+  - id: chat.commands.readme
+    path: .agentic/00.chat/commands/README.md
+  - id: chat.script.startup.start-new-chat
+    path: scripts/00.chat/startup/start-new-chat/script.sh
+-->
+# Start New Chat
+
+`script.sh` is the canonical startup wrapper used by the public `new` command.
+It delegates to `scripts/00.chat/startup/start-chat-session/script.sh`.
+
+This wrapper exists so the public command surface can use a human phrase
+(`new`) while the full startup engine keeps its descriptive capability name.
+
+It can create branches, worktrees, and session logs through the startup engine.
+

package/scripts/00.chat/startup/start-new-chat/script.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# agentic-artifact:
+#   schema: agentic-artifact/v2
+#   id: chat.script.startup.start-new-chat
+#   version: 1
+#   status: active
+#   layer: 00.chat
+#   domain: startup
+#   disciplines:
+#   - agentic
+#   kind: script
+#   purpose: Start a new governed chat session through the startup engine.
+#   portability:
+#     class: required
+#     targets:
+#     - llm-workbench
+#   used_by:
+#   - id: chat.commands.readme
+#     path: .agentic/00.chat/commands/README.md
+#   - id: chat.script.command.dispatcher
+#     path: scripts/00.chat/command/dispatcher/script.sh
+#   effects:
+#   - branches
+#   - worktrees
+#   - writes-files
+#   - stages-files
+exec bash scripts/00.chat/startup/start-chat-session/script.sh "$@"

package/scripts/00.chat/transcript/README.md

@@ -0,0 +1,36 @@
+<!-- agentic-artifact:
+  schema: agentic-artifact/v2
+  id: chat.script.transcript.readme
+  version: 1
+  status: active
+  layer: 00.chat
+  domain: transcript
+  disciplines:
+  - agentic
+  kind: script-domain-readme
+  purpose: Explain transcript discovery and registration scripts.
+  portability:
+    class: required
+    targets:
+    - llm-workbench
+  used_by:
+  - id: chat.workflows.chat-start
+    path: .agentic/00.chat/workflows/chat-start.md
+  - id: chat.script.transcript.register-codex-session-log.readme
+    path: scripts/00.chat/transcript/register-codex-session-log/README.md
+-->
+# Transcript Scripts
+
+Transcript scripts connect chat session logs to assistant transcript evidence.
+The core metadata is provider-neutral:
+
+- `transcript_provider`
+- `transcript_path`
+- `transcript_bytes`
+- `transcript_source`
+
+Codex JSONL discovery is one optional adapter for filling those fields. Other
+assistants can provide transcript byte counts or paths directly.
+
+These scripts inspect local transcript files. They do not upload transcripts or
+depend on network access.

package/scripts/00.chat/transcript/discover-codex-session-log/README.md

@@ -0,0 +1,32 @@
+<!-- agentic-artifact:
+  schema: agentic-artifact/v2
+  id: chat.script.transcript.discover-codex-session-log.readme
+  version: 1
+  status: active
+  layer: 00.chat
+  domain: transcript
+  disciplines:
+  - agentic
+  kind: capability-readme
+  purpose: Explain local Codex transcript discovery for a chat session.
+  portability:
+    class: required
+    targets:
+    - llm-workbench
+  used_by:
+  - id: chat.script.transcript.discover-codex-session-log
+    path: scripts/00.chat/transcript/discover-codex-session-log/script.sh
+  - id: chat.script.transcript.register-codex-session-log
+    path: scripts/00.chat/transcript/register-codex-session-log/script.sh
+-->
+# Discover Codex Session Log
+
+`script.sh` searches the local Codex sessions directory for the JSONL
+transcript that matches a chat session id, branch, or session log path.
+
+It prints the newest matching transcript path. The result is used by commit
+recording and transcript registration so chat metrics can be tied to actual
+local evidence.
+
+The script is read-only. It does not modify the session log or transcript.
+

package/scripts/00.chat/transcript/discover-codex-session-log/script.sh

@@ -0,0 +1,106 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# agentic-artifact:
+#   schema: agentic-artifact/v2
+#   id: chat.script.transcript.discover-codex-session-log
+#   version: 1
+#   status: active
+#   layer: 00.chat
+#   domain: transcript
+#   disciplines:
+#   - agentic
+#   kind: script
+#   purpose: Find the Codex JSONL transcript for a chat session.
+#   portability:
+#     class: required
+#     targets:
+#     - llm-workbench
+#   used_by:
+#   - id: chat.script.transcript.register-codex-session-log
+#     path: scripts/00.chat/transcript/register-codex-session-log/script.sh
+#   - id: chat.script.session-log.record-chat-commit
+#     path: scripts/00.chat/session-log/record-chat-commit/script.sh
+#   effects:
+#   - read-only
+
+usage() {
+  cat <<'EOF'
+Usage:
+  discover-codex-session-log.sh <session-id> [session-log-path]
+
+Finds the Codex JSONL session log that contains the chat session id, branch, or
+session log path. Prints the newest matching path.
+EOF
+}
+
+if [ $# -lt 1 ] || [ $# -gt 2 ]; then
+  usage >&2
+  exit 2
+fi
+
+SESSION_ID="$1"
+SESSION_LOG_PATH="${2:-}"
+CODEX_HOME_DIR="${CODEX_HOME:-${HOME}/.codex}"
+
+if [ -z "${SESSION_ID// }" ]; then
+  echo "ERROR: session id is required." >&2
+  exit 2
+fi
+
+if [ ! -d "$CODEX_HOME_DIR" ]; then
+  echo "ERROR: Codex home directory does not exist: $CODEX_HOME_DIR" >&2
+  exit 1
+fi
+
+TMP_MATCHES="$(mktemp)"
+trap 'rm -f "$TMP_MATCHES"' EXIT
+
+append_match() {
+  local file="$1"
+  local mtime
+
+  if ! mtime="$(stat -c '%Y' "$file" 2>/dev/null)"; then
+    if ! mtime="$(stat -f '%m' "$file" 2>/dev/null)"; then
+      return
+    fi
+  fi
+
+  if [ -z "${mtime// }" ]; then
+    return
+  fi
+
+  printf '%s\t%s\n' "$mtime" "$file" >> "$TMP_MATCHES"
+}
+
+matches_file() {
+  local file="$1"
+
+  grep -Fq "$SESSION_ID" "$file" && return 0
+  grep -Fq "chat/${SESSION_ID}" "$file" && return 0
+
+  if [ -n "${SESSION_LOG_PATH// }" ]; then
+    grep -Fq "$SESSION_LOG_PATH" "$file" && return 0
+  fi
+
+  return 1
+}
+
+for root in "$CODEX_HOME_DIR/sessions" "$CODEX_HOME_DIR/archived_sessions"; do
+  if [ ! -d "$root" ]; then
+    continue
+  fi
+
+  while IFS= read -r -d '' file; do
+    if matches_file "$file"; then
+      append_match "$file"
+    fi
+  done < <(find "$root" -type f -name '*.jsonl' -print0)
+done
+
+if [ ! -s "$TMP_MATCHES" ]; then
+  echo "ERROR: no Codex session log matched session: $SESSION_ID" >&2
+  exit 1
+fi
+
+sort -rn "$TMP_MATCHES" | head -n 1 | cut -f2-

package/scripts/00.chat/transcript/register-codex-session-log/README.md

@@ -0,0 +1,32 @@
+<!-- agentic-artifact:
+  schema: agentic-artifact/v2
+  id: chat.script.transcript.register-codex-session-log.readme
+  version: 1
+  status: active
+  layer: 00.chat
+  domain: transcript
+  disciplines:
+  - agentic
+  kind: capability-readme
+  purpose: Explain recording the local Codex transcript path in the current chat log.
+  portability:
+    class: required
+    targets:
+    - llm-workbench
+  used_by:
+  - id: chat.workflows.chat-start
+    path: .agentic/00.chat/workflows/chat-start.md
+  - id: chat.script.transcript.register-codex-session-log
+    path: scripts/00.chat/transcript/register-codex-session-log/script.sh
+-->
+# Register Codex Session Log
+
+`script.sh` discovers the current chat's local Codex JSONL transcript and
+records that path in the current session log metadata.
+
+Registration lets later commit recording estimate transcript-derived metrics
+without rediscovering the transcript from scratch.
+
+This script writes session-log metadata. It does not create commits or copy
+transcript content into the repository.
+

package/scripts/00.chat/transcript/register-codex-session-log/script.sh

@@ -0,0 +1,115 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# agentic-artifact:
+#   schema: agentic-artifact/v2
+#   id: chat.script.transcript.register-codex-session-log
+#   version: 1
+#   status: active
+#   layer: 00.chat
+#   domain: transcript
+#   disciplines:
+#   - agentic
+#   kind: script
+#   purpose: Record the discovered Codex transcript path as neutral transcript metadata.
+#   portability:
+#     class: required
+#     targets:
+#     - llm-workbench
+#   used_by:
+#   - id: chat.workflows.chat-start
+#     path: .agentic/00.chat/workflows/chat-start.md
+#   - id: chat.script.session-log.record-chat-commit
+#     path: scripts/00.chat/session-log/record-chat-commit/script.sh
+#   effects:
+#   - writes-files
+
+# shellcheck source=../../session-log/paths/lib.sh
+source "scripts/00.chat/session-log/paths/lib.sh"
+
+usage() {
+  cat <<'EOF'
+Usage:
+  register-codex-session-log.sh
+
+Discovers the current chat's Codex JSONL session log and records it as neutral
+transcript metadata in the current chat session log.
+EOF
+}
+
+if [ $# -ne 0 ]; then
+  usage >&2
+  exit 2
+fi
+
+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
+  exit 1
+fi
+
+LOG_FILE="$(chat_log_file_for_session "$SESSION_ID")"
+
+if [ ! -f "$LOG_FILE" ]; then
+  echo "ERROR: missing chat log: $LOG_FILE" >&2
+  exit 1
+fi
+
+CODEX_SESSION_LOG_PATH="$(bash scripts/00.chat/transcript/discover-codex-session-log/script.sh "$SESSION_ID" "$LOG_FILE")"
+
+if [ ! -f "$CODEX_SESSION_LOG_PATH" ]; then
+  echo "ERROR: discovered Codex session log is not a file: $CODEX_SESSION_LOG_PATH" >&2
+  exit 1
+fi
+
+tmp="$(mktemp)"
+
+awk -v transcript_provider="codex" -v transcript_path="$CODEX_SESSION_LOG_PATH" '
+  BEGIN {
+    in_meta = 0
+    wrote_provider = 0
+    wrote_path = 0
+  }
+  /^<!-- agentic-session/ {
+    in_meta = 1
+    print
+    next
+  }
+  in_meta && /^transcript_provider:/ {
+    print "transcript_provider: " transcript_provider
+    wrote_provider = 1
+    next
+  }
+  in_meta && /^transcript_path:/ {
+    print "transcript_path: " transcript_path
+    wrote_path = 1
+    next
+  }
+  in_meta && /^codex_session_log_path:/ {
+    next
+  }
+  in_meta && /^-->/ {
+    if (wrote_provider == 0) {
+      print "transcript_provider: " transcript_provider
+      wrote_provider = 1
+    }
+    if (wrote_path == 0) {
+      print "transcript_path: " transcript_path
+      wrote_path = 1
+    }
+    in_meta = 0
+    print
+    next
+  }
+  {
+    print
+  }
+' "$LOG_FILE" > "$tmp"
+
+mv "$tmp" "$LOG_FILE"
+
+echo "Registered Codex session log:"
+echo "session_log=$LOG_FILE"
+echo "transcript_provider=codex"
+echo "transcript_path=$CODEX_SESSION_LOG_PATH"

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

@@ -0,0 +1,32 @@
+<!-- agentic-artifact:
+  schema: agentic-artifact/v2
+  id: chat.script.worktree.readme
+  version: 1
+  status: active
+  layer: 00.chat
+  domain: worktree
+  disciplines:
+  - agentic
+  kind: script-domain-readme
+  purpose: Explain chat-owned worktree scripts and helpers.
+  portability:
+    class: required
+    targets:
+    - llm-workbench
+  used_by:
+  - id: chat.workflows.chat-start
+    path: .agentic/00.chat/workflows/chat-start.md
+  - id: chat.script.worktree.ensure-chat-worktree.readme
+    path: scripts/00.chat/worktree/ensure-chat-worktree/README.md
+-->
+# Worktree Scripts
+
+Worktree scripts keep chat task work in the right checkout. The root worktree is
+the integration console; each chat should edit in its own sibling worktree.
+
+This domain provides path helpers, write-location checks, dirty-state checks,
+and worktree creation/verification.
+
+The goal is not to make Git clever. The goal is to prevent accidental edits in
+the wrong place.
+

package/scripts/00.chat/worktree/check-write-location/README.md

@@ -0,0 +1,87 @@
+<!-- agentic-artifact:
+  schema: agentic-artifact/v2
+  id: chat.script.worktree.check-write-location.readme
+  version: 1
+  status: active
+  layer: 00.chat
+  domain: worktree
+  disciplines:
+  - agentic
+  kind: capability-readme
+  purpose: Explain how chat work is kept inside chat-owned worktrees rather than the
+    root integration worktree.
+  portability:
+    class: required
+    targets:
+    - llm-workbench
+  used_by:
+  - id: chat.script.worktree.check-write-location
+    path: scripts/00.chat/worktree/check-write-location/script.sh
+  - id: harness.architecture.adr.0017-organize-scripts-by-owner-domain-and-capability
+-->
+# Check Write Location
+
+`script.sh` verifies that task work is happening in the chat-owned worktree for
+the current `chat/*` branch.
+
+The root worktree is the integration console. It is where completed chat work is
+reviewed, merged, and coordinated. Task edits should happen in the sibling
+worktree created for that chat branch.
+
+## Mental Model
+
+Each chat branch has one canonical worktree path. If an agent edits from the
+root integration worktree, it can mix task work with local integration state. If
+an agent edits a chat branch from an unexpected worktree, the harness can no
+longer rely on its branch-to-directory ownership model.
+
+This gate protects that invariant before write-heavy or commit-boundary work.
+
+## Checks
+
+The script verifies:
+
+- the current repository path is not the primary/root worktree, unless explicit
+  root maintenance is allowed
+- the current branch is a `chat/*` branch
+- the current path matches the canonical chat worktree path for that branch
+
+On success it prints:
+
+```txt
+chat-worktree
+```
+
+## Root Maintenance Escape Hatch
+
+Root maintenance is allowed only when explicit:
+
+```bash
+AGENTIC_ALLOW_ROOT_WRITE=1 bash scripts/00.chat/worktree/check-write-location/script.sh
+```
+
+or:
+
+```bash
+bash scripts/00.chat/worktree/check-write-location/script.sh --allow-root-maintenance
+```
+
+This is for intentional root/integration maintenance, not ordinary task work.
+
+## What This Does Not Do
+
+- It does not move files into the chat worktree.
+- It does not create the chat worktree.
+- It does not switch branches.
+- It does not decide that root work is safe.
+- It does not commit anything.
+
+## Compatibility
+
+The old shared path remains available:
+
+```bash
+scripts/00.chat/worktree/check-write-location/script.sh
+```
+
+That file is now a compatibility wrapper around the canonical implementation.