llm-wb 0.1.0-beta.0

package/scripts/00.chat/main-refresh/rehearse-refresh-from-main/README.md

@@ -0,0 +1,34 @@
+<!-- agentic-artifact:
+  schema: agentic-artifact/v2
+  id: chat.script.main-refresh.rehearse-refresh-from-main.readme
+  version: 1
+  status: active
+  layer: 00.chat
+  domain: main-refresh
+  disciplines:
+  - agentic
+  kind: guide
+  purpose: Explain how the harness rehearses refreshing a chat branch from main before
+    applying it.
+  portability:
+    class: required
+    targets:
+    - llm-workbench
+  used_by:
+  - id: chat.script.main-refresh.rehearse-refresh-from-main
+    path: scripts/00.chat/main-refresh/rehearse-refresh-from-main/script.sh
+  - id: chat.script.main-refresh.rehearse-refresh-from-main.smoke-test
+    path: scripts/00.chat/main-refresh/rehearse-refresh-from-main/smoke-test.sh
+-->
+# Rehearse Refresh From Main
+
+This capability answers: would refreshing this chat branch from `main` work
+safely?
+
+It creates a temporary preflight branch and worktree from the current chat
+branch, then merges the base branch there. The active chat worktree is left
+untouched. If the merge succeeds, the temporary branch contains the tested merge
+result and can be applied with `apply-rehearsed-refresh`.
+
+Use this when a chat branch has real work and a direct refresh would be too
+risky to perform without rehearsal.

package/scripts/00.chat/main-refresh/rehearse-refresh-from-main/script.sh

@@ -0,0 +1,124 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# agentic-artifact:
+#   schema: agentic-artifact/v2
+#   id: chat.script.main-refresh.rehearse-refresh-from-main
+#   version: 1
+#   status: active
+#   layer: 00.chat
+#   domain: main-refresh
+#   disciplines:
+#   - agentic
+#   kind: script
+#   purpose: Rehearse refreshing a chat branch from main in a temporary worktree.
+#   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: chat.script.main-refresh.rehearse-refresh-from-main.smoke-test
+#     path: scripts/00.chat/main-refresh/rehearse-refresh-from-main/smoke-test.sh
+#   effects:
+#   - branches
+#   - commits
+#   - worktrees
+
+usage() {
+  cat <<'EOF'
+Usage:
+  script.sh [base-branch]
+
+Creates a temporary worktree and branch from the current chat branch, then
+attempts to merge the base branch there. The active chat worktree is left
+untouched. If the merge succeeds, the preflight branch contains the merge
+commit and can be applied with apply-rehearsed-refresh.
+EOF
+}
+
+BASE_BRANCH="${1:-main}"
+
+if [ $# -gt 1 ]; then
+  usage >&2
+  exit 2
+fi
+
+case "$BASE_BRANCH" in
+  -h|--help)
+    usage
+    exit 0
+    ;;
+esac
+
+if ! git show-ref --verify --quiet "refs/heads/${BASE_BRANCH}"; then
+  echo "ERROR: base branch does not exist: ${BASE_BRANCH}" >&2
+  exit 1
+fi
+
+CLASSIFICATION="$(bash scripts/00.chat/main-refresh/classify-refresh-readiness/script.sh "$BASE_BRANCH" | sed -n 's/^classification=//p' | head -n 1)"
+
+if [ "$CLASSIFICATION" != "clean" ]; then
+  echo "ERROR: preflight requires a clean chat worktree." >&2
+  echo "Classifier reported: ${CLASSIFICATION}" >&2
+  echo "Checkpoint or recover dirty state before preflighting main refresh." >&2
+  exit 1
+fi
+
+CURRENT_BRANCH="$(git branch --show-current)"
+
+case "$CURRENT_BRANCH" in
+  chat/*)
+    ;;
+  *)
+    echo "ERROR: current branch is not a chat branch: ${CURRENT_BRANCH}" >&2
+    exit 1
+    ;;
+esac
+
+CURRENT_HEAD="$(git rev-parse HEAD)"
+RAW_SAFE_BRANCH="$(printf '%s' "$CURRENT_BRANCH" | tr -c 'A-Za-z0-9._-' '-')"
+SAFE_BRANCH_PREFIX="$(printf '%s' "$RAW_SAFE_BRANCH" | cut -c1-48 | sed -E 's/[-.]+$//')"
+if [ -z "${SAFE_BRANCH_PREFIX// }" ]; then
+  SAFE_BRANCH_PREFIX="chat"
+fi
+SAFE_BRANCH="${SAFE_BRANCH_PREFIX}-$(git rev-parse --short=12 HEAD)"
+STAMP="$(date -u +%Y%m%d%H%M%S)"
+PREFLIGHT_BRANCH="agentic/preflight/${SAFE_BRANCH}/${STAMP}"
+PREFLIGHT_ROOT="${TMPDIR:-/tmp}/agentic-main-refresh-preflight"
+PREFLIGHT_WORKTREE="${PREFLIGHT_ROOT}/${SAFE_BRANCH}-${STAMP}"
+MERGE_OUT="${PREFLIGHT_ROOT}/${SAFE_BRANCH}-${STAMP}.merge.out"
+MERGE_ERR="${PREFLIGHT_ROOT}/${SAFE_BRANCH}-${STAMP}.merge.err"
+
+mkdir -p "$PREFLIGHT_ROOT"
+
+git branch "$PREFLIGHT_BRANCH" "$CURRENT_HEAD"
+git worktree add -q "$PREFLIGHT_WORKTREE" "$PREFLIGHT_BRANCH"
+
+set +e
+git -C "$PREFLIGHT_WORKTREE" merge --no-ff --no-edit "$BASE_BRANCH" \
+  > "$MERGE_OUT" 2> "$MERGE_ERR"
+MERGE_STATUS="$?"
+set -e
+
+echo "preflight_branch=${PREFLIGHT_BRANCH}"
+echo "preflight_worktree=${PREFLIGHT_WORKTREE}"
+echo "source_branch=${CURRENT_BRANCH}"
+echo "source_head=${CURRENT_HEAD}"
+echo "base_branch=${BASE_BRANCH}"
+
+if [ "$MERGE_STATUS" -ne 0 ]; then
+  echo "result=conflict-or-failed"
+  echo "conflict_paths<<EOF"
+  git -C "$PREFLIGHT_WORKTREE" diff --name-only --diff-filter=U | sort -u
+  echo "EOF"
+  echo "Merge output:"
+  sed 's/^/  /' "$MERGE_ERR"
+  exit 1
+fi
+
+echo "result=clean-merge"
+echo "preflight_head=$(git -C "$PREFLIGHT_WORKTREE" rev-parse HEAD)"
+echo "Apply with:"
+echo "  bash scripts/00.chat/main-refresh/apply-rehearsed-refresh/script.sh ${PREFLIGHT_BRANCH}"

package/scripts/00.chat/main-refresh/rehearse-refresh-from-main/smoke-test.sh

@@ -0,0 +1,257 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# agentic-artifact:
+#   schema: agentic-artifact/v2
+#   id: chat.script.main-refresh.rehearse-refresh-from-main.smoke-test
+#   version: 1
+#   status: active
+#   layer: 00.chat
+#   domain: main-refresh
+#   disciplines:
+#   - agentic
+#   kind: script
+#   purpose: Smoke test rehearsed main refresh and apply behavior.
+#   portability:
+#     class: reusable
+#     targets:
+#     - llm-workbench
+#   used_by:
+#   - id: chat.workflows.chat-refresh-from-main
+#     path: .agentic/00.chat/workflows/chat-refresh-from-main.md
+#   - id: chat.script.main-refresh.rehearse-refresh-from-main
+#     path: scripts/00.chat/main-refresh/rehearse-refresh-from-main/script.sh
+#   effects:
+#   - branches
+#   - commits
+#   - destructive
+#   - worktrees
+#   - writes-files
+
+fail() {
+  echo "FAIL: $*" >&2
+  exit 1
+}
+
+SOURCE_ROOT="$(git rev-parse --show-toplevel)"
+TMP_ROOT="$(mktemp -d "${TMPDIR:-/tmp}/main-refresh-preflight-smoke.XXXXXX")"
+
+cleanup() {
+  if [ -n "${PREFLIGHT_WORKTREE:-}" ] && [ -d "$PREFLIGHT_WORKTREE" ]; then
+    git -C "$REPO" worktree remove -f "$PREFLIGHT_WORKTREE" >/dev/null 2>&1 || true
+  fi
+  if [ -n "${DIRTY_PREFLIGHT_WORKTREE:-}" ] && [ -d "$DIRTY_PREFLIGHT_WORKTREE" ]; then
+    git -C "$REPO" worktree remove -f "$DIRTY_PREFLIGHT_WORKTREE" >/dev/null 2>&1 || true
+  fi
+  if [ -n "${PREFLIGHT_BRANCH:-}" ]; then
+    git -C "$REPO" branch -D "$PREFLIGHT_BRANCH" >/dev/null 2>&1 || true
+  fi
+  if [ -n "${DIRTY_PREFLIGHT_BRANCH:-}" ]; then
+    git -C "$REPO" branch -D "$DIRTY_PREFLIGHT_BRANCH" >/dev/null 2>&1 || true
+  fi
+  if [ -n "${STALE_PREFLIGHT_WORKTREE:-}" ] && [ -d "$STALE_PREFLIGHT_WORKTREE" ]; then
+    git -C "$REPO" worktree remove -f "$STALE_PREFLIGHT_WORKTREE" >/dev/null 2>&1 || true
+  fi
+  if [ -n "${UNIQUE_PREFLIGHT_WORKTREE:-}" ] && [ -d "$UNIQUE_PREFLIGHT_WORKTREE" ]; then
+    git -C "$REPO" worktree remove -f "$UNIQUE_PREFLIGHT_WORKTREE" >/dev/null 2>&1 || true
+  fi
+  if [ -n "${STALE_PREFLIGHT_BRANCH:-}" ]; then
+    git -C "$REPO" branch -D "$STALE_PREFLIGHT_BRANCH" >/dev/null 2>&1 || true
+  fi
+  if [ -n "${UNIQUE_PREFLIGHT_BRANCH:-}" ]; then
+    git -C "$REPO" branch -D "$UNIQUE_PREFLIGHT_BRANCH" >/dev/null 2>&1 || true
+  fi
+  rm -rf "$TMP_ROOT"
+}
+
+trap cleanup EXIT
+
+REPO="$TMP_ROOT/repo"
+SESSION_ID="2026-06-17-00-01-preflight-chat-with-a-long-trailing-hyphen-name-that-needs-safe-preflight-shortening-"
+SESSION_LOG="commitLogs/2026/jun/17/${SESSION_ID}/README.md"
+
+mkdir -p \
+  "$REPO/scripts/00.chat/main-refresh/classify-refresh-readiness" \
+  "$REPO/scripts/00.chat/main-refresh/rehearse-refresh-from-main" \
+  "$REPO/scripts/00.chat/main-refresh/apply-rehearsed-refresh" \
+  "$REPO/scripts/00.chat/reporting/generate-commit-log-summary" \
+  "$REPO/scripts/00.chat/session-log/paths" \
+  "$REPO/$(dirname "$SESSION_LOG")"
+
+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/reporting/generate-commit-log-summary/script.sh" \
+  "$REPO/scripts/00.chat/reporting/generate-commit-log-summary/script.sh"
+cp "$SOURCE_ROOT/scripts/00.chat/main-refresh/classify-refresh-readiness/script.sh" \
+  "$REPO/scripts/00.chat/main-refresh/classify-refresh-readiness/script.sh"
+cp "$SOURCE_ROOT/scripts/00.chat/main-refresh/rehearse-refresh-from-main/script.sh" \
+  "$REPO/scripts/00.chat/main-refresh/rehearse-refresh-from-main/script.sh"
+cp "$SOURCE_ROOT/scripts/00.chat/main-refresh/apply-rehearsed-refresh/script.sh" \
+  "$REPO/scripts/00.chat/main-refresh/apply-rehearsed-refresh/script.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"
+
+cat > "$REPO/README.md" <<'EOF'
+base
+EOF
+
+cat > "$REPO/$SESSION_LOG" <<EOF
+# Chat Session: ${SESSION_ID}
+
+<!-- agentic-session
+id: ${SESSION_ID}
+chat_duration: 10s
+estimated_chat_tokens: 50 tokens
+-->
+EOF
+
+(
+  cd "$REPO"
+  bash scripts/00.chat/reporting/generate-commit-log-summary/script.sh >/dev/null
+)
+
+git -C "$REPO" add .
+git -C "$REPO" commit -q -m "base"
+git -C "$REPO" switch -q -c "chat/${SESSION_ID}"
+
+git -C "$REPO" switch -q main
+printf 'main update\n' >> "$REPO/README.md"
+git -C "$REPO" add README.md
+git -C "$REPO" commit -q -m "update main"
+git -C "$REPO" switch -q "chat/${SESSION_ID}"
+
+PREFLIGHT_OUTPUT="$(
+  cd "$REPO"
+  TMPDIR="$TMP_ROOT" bash scripts/00.chat/main-refresh/rehearse-refresh-from-main/script.sh
+)"
+
+PREFLIGHT_BRANCH="$(printf '%s\n' "$PREFLIGHT_OUTPUT" | sed -n 's/^preflight_branch=//p')"
+PREFLIGHT_WORKTREE="$(printf '%s\n' "$PREFLIGHT_OUTPUT" | sed -n 's/^preflight_worktree=//p')"
+PREFLIGHT_HEAD="$(printf '%s\n' "$PREFLIGHT_OUTPUT" | sed -n 's/^preflight_head=//p')"
+
+if [ -z "$PREFLIGHT_BRANCH" ] || [ -z "$PREFLIGHT_WORKTREE" ] || [ -z "$PREFLIGHT_HEAD" ]; then
+  fail "preflight did not report branch, worktree, and head"
+fi
+
+PREFLIGHT_NAMESPACE="${PREFLIGHT_BRANCH%/*}"
+PREFLIGHT_NAMESPACE="${PREFLIGHT_NAMESPACE##*/}"
+if [ "${#PREFLIGHT_NAMESPACE}" -gt 64 ]; then
+  fail "preflight namespace was not shortened: $PREFLIGHT_NAMESPACE"
+fi
+
+if ! printf '%s\n' "$PREFLIGHT_OUTPUT" | grep -q '^result=clean-merge$'; then
+  fail "preflight did not report a clean merge"
+fi
+
+printf 'dirty preflight residue\n' >> "$PREFLIGHT_WORKTREE/preflight-note.txt"
+
+set +e
+DIRTY_PROMOTE_OUTPUT="$({
+  cd "$REPO"
+  bash scripts/00.chat/main-refresh/apply-rehearsed-refresh/script.sh "$PREFLIGHT_BRANCH"
+} 2> "$TMP_ROOT/dirty-promote.err")"
+DIRTY_PROMOTE_STATUS="$?"
+set -e
+
+if [ "$DIRTY_PROMOTE_STATUS" -eq 0 ]; then
+  fail "apply succeeded with dirty preflight worktree"
+fi
+
+if ! grep -q "refusing to clean dirty preflight worktree" "$TMP_ROOT/dirty-promote.err"; then
+  fail "dirty preflight worktree failure was not explained"
+fi
+
+if [ "$(git -C "$REPO" rev-parse HEAD)" = "$PREFLIGHT_HEAD" ]; then
+  fail "dirty cleanup failure still applied to chat branch"
+fi
+
+rm -f "$PREFLIGHT_WORKTREE/preflight-note.txt"
+
+PREFLIGHT_PREFIX="${PREFLIGHT_BRANCH%/*}"
+STALE_PREFLIGHT_BRANCH="${PREFLIGHT_PREFIX}/20000101000000"
+STALE_PREFLIGHT_WORKTREE="$TMP_ROOT/stale-preflight-worktree"
+git -C "$REPO" branch "$STALE_PREFLIGHT_BRANCH" HEAD
+git -C "$REPO" worktree add --quiet "$STALE_PREFLIGHT_WORKTREE" "$STALE_PREFLIGHT_BRANCH"
+
+UNIQUE_PREFLIGHT_BRANCH="${PREFLIGHT_PREFIX}/20000101000001"
+UNIQUE_PREFLIGHT_WORKTREE="$TMP_ROOT/unique-preflight-worktree"
+git -C "$REPO" branch "$UNIQUE_PREFLIGHT_BRANCH" HEAD
+git -C "$REPO" worktree add --quiet "$UNIQUE_PREFLIGHT_WORKTREE" "$UNIQUE_PREFLIGHT_BRANCH"
+printf 'unique stale preflight\n' >> "$UNIQUE_PREFLIGHT_WORKTREE/unique.txt"
+git -C "$UNIQUE_PREFLIGHT_WORKTREE" add unique.txt
+git -C "$UNIQUE_PREFLIGHT_WORKTREE" commit -q -m "unique stale preflight work"
+
+PROMOTE_OUTPUT="$(
+  cd "$REPO"
+  bash scripts/00.chat/main-refresh/apply-rehearsed-refresh/script.sh "$PREFLIGHT_BRANCH"
+)"
+
+if ! grep -q "main update" "$REPO/README.md"; then
+  fail "promoted chat branch does not include main update"
+fi
+
+if [ "$(git -C "$REPO" rev-parse HEAD)" != "$PREFLIGHT_HEAD" ]; then
+  fail "applied chat branch does not point at preflight head"
+fi
+
+if git -C "$REPO" show-ref --verify --quiet "refs/heads/${PREFLIGHT_BRANCH}"; then
+  fail "preflight branch still exists after successful promotion"
+fi
+
+if git -C "$REPO" worktree list --porcelain | grep -Fqx "worktree ${PREFLIGHT_WORKTREE}"; then
+  fail "preflight worktree still exists after successful promotion"
+fi
+
+if ! printf '%s\n' "$PROMOTE_OUTPUT" | grep -q '^cleanup_result=removed-worktree-and-deleted-branch$'; then
+  fail "apply did not report cleanup result"
+fi
+
+if git -C "$REPO" show-ref --verify --quiet "refs/heads/${STALE_PREFLIGHT_BRANCH}"; then
+  fail "ancestor stale preflight branch still exists after promotion"
+fi
+
+if git -C "$REPO" worktree list --porcelain | grep -Fqx "worktree ${STALE_PREFLIGHT_WORKTREE}"; then
+  fail "ancestor stale preflight worktree still exists after promotion"
+fi
+
+if ! printf '%s\n' "$PROMOTE_OUTPUT" | grep -q "^stale_preflight_removed=${STALE_PREFLIGHT_BRANCH} "; then
+  fail "apply did not report stale preflight removal"
+fi
+
+if ! git -C "$REPO" show-ref --verify --quiet "refs/heads/${UNIQUE_PREFLIGHT_BRANCH}"; then
+  fail "unique stale preflight branch was deleted"
+fi
+
+if ! git -C "$REPO" worktree list --porcelain | grep -Fqx "worktree ${UNIQUE_PREFLIGHT_WORKTREE}"; then
+  fail "unique stale preflight worktree was removed"
+fi
+
+if ! printf '%s\n' "$PROMOTE_OUTPUT" | grep -q "^stale_preflight_skipped=${UNIQUE_PREFLIGHT_BRANCH} reason=unique-commits-not-in-promoted-head$"; then
+  fail "apply did not report unique stale preflight skip"
+fi
+
+DIRTY_PREFLIGHT_BRANCH="topic/not-preflight"
+git -C "$REPO" branch "$DIRTY_PREFLIGHT_BRANCH" HEAD
+set +e
+(
+  cd "$REPO"
+  bash scripts/00.chat/main-refresh/apply-rehearsed-refresh/script.sh "$DIRTY_PREFLIGHT_BRANCH"
+) > "$TMP_ROOT/non-preflight.out" 2> "$TMP_ROOT/non-preflight.err"
+NON_PREFLIGHT_STATUS="$?"
+set -e
+
+if [ "$NON_PREFLIGHT_STATUS" -eq 0 ]; then
+  fail "apply accepted a non-preflight branch"
+fi
+
+if ! grep -q "refusing non-preflight branch" "$TMP_ROOT/non-preflight.err"; then
+  fail "non-preflight branch failure was not explained"
+fi
+
+if [ -n "$(git -C "$REPO" status --porcelain)" ]; then
+  fail "repo is dirty after preflight promotion"
+fi
+
+echo "main refresh rehearsal smoke test passed."

package/scripts/00.chat/main-refresh/show-main-update-status/README.md

@@ -0,0 +1,31 @@
+<!-- agentic-artifact:
+  schema: agentic-artifact/v2
+  id: chat.script.main-refresh.show-main-update-status.readme
+  version: 1
+  status: active
+  layer: 00.chat
+  domain: main-refresh
+  disciplines:
+  - agentic
+  kind: guide
+  purpose: Explain the local main update status report for chat branches.
+  portability:
+    class: required
+    targets:
+    - llm-workbench
+  used_by:
+  - id: chat.script.main-refresh.show-main-update-status
+    path: scripts/00.chat/main-refresh/show-main-update-status/script.sh
+-->
+# Show Main Update Status
+
+This read-only capability answers: has local `main` moved relative to the chat
+branches?
+
+It prints each local branch's ahead/behind count relative to the selected base
+branch, defaulting to `main`. It does not fetch, merge, rebase, stage, or write
+files. If remotes exist, it reminds the operator to fetch before treating the
+comparison as current.
+
+Use this near the start of a main-refresh conversation so the human and agent
+share the same branch map before choosing a refresh path.

package/scripts/00.chat/main-refresh/show-main-update-status/script.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# agentic-artifact:
+#   schema: agentic-artifact/v2
+#   id: chat.script.main-refresh.show-main-update-status
+#   version: 1
+#   status: active
+#   layer: 00.chat
+#   domain: main-refresh
+#   disciplines:
+#   - agentic
+#   kind: script
+#   purpose: Show whether local chat branches are ahead of or behind the base branch.
+#   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
+
+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)"
+
+if [ -z "$current_branch" ]; then
+  echo "ERROR: current HEAD is detached." >&2
+  exit 1
+fi
+
+echo "Base branch: ${BASE_BRANCH}"
+echo "Current branch: ${current_branch}"
+
+if git remote | grep -q .; then
+  echo "Remote freshness: remotes configured; run git fetch --prune before relying on remote comparisons."
+else
+  echo "Remote freshness: no remotes configured; comparisons are local only."
+fi
+
+echo
+printf '%-72s %8s %8s %s\n' "branch" "behind" "ahead" "state"
+
+git branch --format='%(refname:short)' | while IFS= read -r branch; do
+  if [ "$branch" = "$BASE_BRANCH" ]; then
+    continue
+  fi
+
+  counts="$(git rev-list --left-right --count "${BASE_BRANCH}...${branch}")"
+  behind="${counts%%	*}"
+  ahead="${counts##*	}"
+
+  if [ "$behind" = "0" ] && [ "$ahead" = "0" ]; then
+    state="even"
+  elif [ "$behind" = "0" ]; then
+    state="ahead"
+  elif [ "$ahead" = "0" ]; then
+    state="behind"
+  else
+    state="diverged"
+  fi
+
+  printf '%-72s %8s %8s %s\n' "$branch" "$behind" "$ahead" "$state"
+done

package/scripts/00.chat/main-refresh/verify-conflict-audit/README.md

@@ -0,0 +1,37 @@
+<!-- agentic-artifact:
+  schema: agentic-artifact/v2
+  id: chat.script.main-refresh.verify-conflict-audit.readme
+  version: 1
+  status: active
+  layer: 00.chat
+  domain: main-refresh
+  disciplines:
+  - agentic
+  kind: capability-readme
+  purpose: Explain verification of main-refresh conflict audit entries.
+  portability:
+    class: required
+    targets:
+    - llm-workbench
+  used_by:
+  - id: chat.script.main-refresh.verify-conflict-audit
+    path: scripts/00.chat/main-refresh/verify-conflict-audit/script.sh
+  - id: chat.workflows.chat-refresh-from-main
+    path: .agentic/00.chat/workflows/chat-refresh-from-main.md
+-->
+# Verify Main Refresh Conflict Audit
+
+`script.sh` verifies that known main-refresh conflict paths have matching
+entries in a chat session log's `## Main Refresh Conflicts` section.
+
+Use it before applying or promoting a rehearsed refresh that encountered
+conflicts. If conflicts are still unresolved, the script can discover them from
+the Git index. If conflicts have already been resolved in the preflight
+worktree, pass the captured path list explicitly with `--path` or
+`--paths-file`.
+
+```bash
+bash scripts/00.chat/main-refresh/verify-conflict-audit/script.sh \
+  --session-log commitLogs/.../README.md \
+  --path docs/example-conflict.md
+```