llm-wb 0.1.0-beta.0

package/scripts/00.chat/migration/audit-chat-layer-migration/script.sh

@@ -0,0 +1,127 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# agentic-artifact:
+#   schema: agentic-artifact/v2
+#   id: chat.script.migration.audit-chat-layer-migration
+#   version: 1
+#   status: active
+#   layer: 00.chat
+#   domain: migration
+#   disciplines:
+#   - agentic
+#   kind: script
+#   purpose: Verify canonical chat-layer files and retired compatibility paths.
+#   portability:
+#     class: required
+#     targets:
+#     - llm-workbench
+#   used_by:
+#   - id: chat.migration-plan
+#     path: .agentic/00.chat/migration-plan.md
+#   effects:
+#   - read-only
+
+required_paths=(
+  "package.json"
+  ".agentic/00.chat/README.md"
+  ".agentic/00.chat/migration-plan.md"
+  ".agentic/00.chat/workflows/README.md"
+  ".agentic/00.chat/workflows/chat-start.md"
+  ".agentic/00.chat/workflows/chat-commit.md"
+  ".agentic/00.chat/workflows/chat-refresh-from-main.md"
+  ".agentic/00.chat/workflows/chat-promote-to-main.md"
+  ".agentic/00.chat/workflows/chat-cleanup.md"
+  ".agentic/00.chat/workflows/chat-reporting.md"
+  ".agentic/00.chat/workflows/chat-upstream-reusable-lesson.md"
+  ".agentic/00.chat/workflows/bootstrap-chat-workbench-repo.md"
+  ".agentic/00.chat/checklists/before-commit.md"
+  ".agentic/00.chat/skills/session-summary.md"
+)
+
+retired_paths=(
+  ".agentic/shared/workflows/chat-start-interview.md"
+  ".agentic/shared/workflows/main-updated.md"
+  ".agentic/shared/workflows/local-convergence.md"
+  ".agentic/shared/checklists/before-commit.md"
+  ".agentic/shared/workflows/default.md"
+  ".agentic/01.harness/workflows/default.md"
+)
+
+failures=0
+
+check_file() {
+  local path="$1"
+  local label="$2"
+
+  if [ -f "$path" ]; then
+    echo "OK: ${label}: ${path}"
+  else
+    echo "ERROR: missing ${label}: ${path}" >&2
+    failures=$((failures + 1))
+  fi
+}
+
+check_absent() {
+  local path="$1"
+  local label="$2"
+
+  if [ -e "$path" ]; then
+    echo "ERROR: retired ${label} still exists: ${path}" >&2
+    failures=$((failures + 1))
+  else
+    echo "OK: retired ${label} absent: ${path}"
+  fi
+}
+
+echo "Canonical chat layer files"
+for path in "${required_paths[@]}"; do
+  check_file "$path" "canonical file"
+done
+
+echo
+echo "Retired compatibility paths"
+for path in "${retired_paths[@]}"; do
+  check_absent "$path" "path"
+done
+
+echo
+echo "Retired compatibility references"
+retired_matches="$(
+  grep -RIlE \
+    '\.agentic/shared/workflows/(chat-start-interview|main-updated|local-convergence|default)\.md|\.agentic/shared/checklists/before-commit\.md|\.agentic/01.harness/workflows/default\.md' \
+    .agentic scripts docs 2>/dev/null \
+    | grep -v -E '^\.agentic/00\.chat/migration-plan\.md$|^scripts/00\.chat/migration/audit-chat-layer-migration/script\.sh$' \
+    || true
+)"
+
+if [ -z "$retired_matches" ]; then
+  echo "OK: no retired compatibility references found."
+else
+  echo "Retired compatibility reference files:"
+  printf '%s\n' "$retired_matches"
+  failures=$((failures + 1))
+fi
+
+echo
+echo "Retired aggregate summary policy references"
+summary_matches="$(
+  grep -RIl 'commitLogs/README.md' .agentic scripts docs 2>/dev/null \
+    | grep -v -E '^\.agentic/00\.chat/migration-plan\.md$|^scripts/00\.chat/migration/audit-chat-layer-migration/script\.sh$' \
+    || true
+)"
+
+if [ -z "$summary_matches" ]; then
+  echo "OK: no commitLogs/README.md policy references found."
+else
+  echo "Policy reference files:"
+  printf '%s\n' "$summary_matches"
+fi
+
+if [ "$failures" -gt 0 ]; then
+  echo "Chat layer migration audit failed." >&2
+  exit 1
+fi
+
+echo
+echo "Chat layer migration audit completed."

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

@@ -0,0 +1,30 @@
+<!-- agentic-artifact:
+  schema: agentic-artifact/v2
+  id: chat.script.recovery.readme
+  version: 1
+  status: active
+  layer: 00.chat
+  domain: recovery
+  disciplines:
+  - agentic
+  kind: script-domain-readme
+  purpose: Explain recovery scripts for wrong-worktree chat edits.
+  portability:
+    class: required
+    targets:
+    - llm-workbench
+  used_by:
+  - id: chat.workflows.chat-commit
+    path: .agentic/00.chat/workflows/chat-commit.md
+  - id: chat.script.recovery.import-active-paths-to-chat-worktree.readme
+    path: scripts/00.chat/recovery/import-active-paths-to-chat-worktree/README.md
+-->
+# Recovery Scripts
+
+Recovery scripts handle exceptional chat lifecycle situations, especially work
+that was edited in the wrong checkout.
+
+Normal task work should happen directly in the chat-owned worktree. Recovery
+scripts exist so explicit paths can be moved back into the right worktree
+without normalizing broad or ambiguous repair actions.
+

package/scripts/00.chat/recovery/import-active-paths-to-chat-worktree/README.md

@@ -0,0 +1,76 @@
+<!-- agentic-artifact:
+  schema: agentic-artifact/v2
+  id: chat.script.recovery.import-active-paths-to-chat-worktree.readme
+  version: 1
+  status: active
+  layer: 00.chat
+  domain: recovery
+  disciplines:
+  - agentic
+  kind: guide
+  purpose: Explain governed recovery import from an active worktree into a chat-owned
+    worktree.
+  portability:
+    class: required
+    targets:
+    - llm-workbench
+  used_by:
+  - id: chat.script.recovery.import-active-paths-to-chat-worktree
+    path: scripts/00.chat/recovery/import-active-paths-to-chat-worktree/script.sh
+-->
+# Import Active Paths To Chat Worktree
+
+This capability is for recovery, not normal chat work.
+
+Normal chat task work should happen directly in the chat-owned worktree recorded
+in the session log. That worktree has its own files, index, and branch, so task
+commits can be prepared without touching the root integration worktree.
+
+Sometimes edits happen in the wrong place anyway: an IDE opens the root checkout,
+a human changes files before noticing the active path, or an older workflow
+leaves useful changes outside the chat-owned worktree. In that case the harness
+needs a governed way to bring only the approved files back into the session's
+chat worktree.
+
+`script.sh` does that import.
+
+It reads the session log, finds the chat branch and chat-owned worktree, then
+copies only the explicit repository-relative paths passed on the command line
+from the source worktree into the chat-owned worktree. Existing source paths are
+copied. Missing source paths are treated as deletions. The same paths are staged
+in the chat-owned worktree.
+
+The script refuses broad or ambiguous recovery:
+
+- no paths means no import
+- absolute paths and `..` paths are rejected
+- the source and target worktrees cannot be the same path
+- the target must be the session's chat branch
+- the target chat-owned worktree must be clean before import
+
+That last rule matters. Recovery should not hide existing target work. If the
+chat-owned worktree is already dirty, inspect, commit, checkpoint, or otherwise
+resolve that state first.
+
+Example:
+
+```bash
+bash scripts/00.chat/recovery/import-active-paths-to-chat-worktree/script.sh \
+  --session-log commitLogs/2026/jun/19/example-session/README.md \
+  --source-worktree /home/owner/projects/entity-builder-harness-001 \
+  -- docs/example.md scripts/example.sh
+```
+
+After the import, continue from the chat-owned worktree and run the normal
+before-commit gates.
+
+## Relationship To Older Helpers
+
+The older `with-chat-branch.sh` and `stage-active-worktree-paths.sh` helpers
+came from the commit-boundary-only model, where commands could be run in a
+temporary isolated session worktree while normal edits happened elsewhere.
+
+The current harness model is stricter: each chat owns its worktree. This
+capability keeps the useful recovery behavior, but names it as recovery import
+instead of normal commit flow. The old shared helpers have been retired so new
+instructions and scripts do not accidentally revive the earlier model.

package/scripts/00.chat/recovery/import-active-paths-to-chat-worktree/script.sh

@@ -0,0 +1,212 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# agentic-artifact:
+#   schema: agentic-artifact/v2
+#   id: chat.script.recovery.import-active-paths-to-chat-worktree
+#   version: 1
+#   status: active
+#   layer: 00.chat
+#   domain: recovery
+#   disciplines:
+#   - agentic
+#   kind: script
+#   purpose: Import explicit paths from an active worktree into a session's chat-owned
+#     worktree.
+#   portability:
+#     class: required
+#     targets:
+#     - llm-workbench
+#   used_by:
+#   - id: chat.script.recovery.import-active-paths-to-chat-worktree.readme
+#     path: scripts/00.chat/recovery/import-active-paths-to-chat-worktree/README.md
+#   effects:
+#   - stages-files
+#   - writes-files
+
+usage() {
+  cat <<'EOF'
+Usage:
+  script.sh --session-log <path> [--source-worktree <path>] -- <path>...
+
+Imports explicit repository-relative paths from the source worktree into the
+chat-owned worktree recorded in a session log, then stages those paths in the
+chat-owned worktree.
+
+This is recovery tooling for edits made in the wrong worktree. Normal chat task
+work should happen directly in the chat-owned worktree.
+EOF
+}
+
+SESSION_LOG="${AGENTIC_SESSION_LOG:-}"
+SOURCE_WORKTREE="${AGENTIC_ACTIVE_WORKTREE:-}"
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --session-log)
+      if [ $# -lt 2 ]; then
+        usage >&2
+        exit 2
+      fi
+      SESSION_LOG="$2"
+      shift 2
+      ;;
+    --source-worktree)
+      if [ $# -lt 2 ]; then
+        usage >&2
+        exit 2
+      fi
+      SOURCE_WORKTREE="$2"
+      shift 2
+      ;;
+    --)
+      shift
+      break
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      break
+      ;;
+  esac
+done
+
+if [ $# -eq 0 ]; then
+  usage >&2
+  exit 2
+fi
+
+validate_path() {
+  local path="$1"
+
+  if [ -z "${path// }" ]; then
+    echo "ERROR: empty path is not allowed." >&2
+    exit 1
+  fi
+
+  case "$path" in
+    /*|../*|*/../*|*/..|.)
+      echo "ERROR: path must be a repository-relative path without '..': $path" >&2
+      exit 1
+      ;;
+  esac
+}
+
+for path in "$@"; do
+  validate_path "$path"
+done
+
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+REPO_ROOT="$(cd "$REPO_ROOT" && pwd -P)"
+
+# shellcheck source=../../worktree/paths/lib.sh
+source "$REPO_ROOT/scripts/00.chat/worktree/paths/lib.sh"
+# shellcheck source=../../session-log/paths/lib.sh
+source "$REPO_ROOT/scripts/00.chat/session-log/paths/lib.sh"
+
+if [ -z "${SOURCE_WORKTREE// }" ]; then
+  SOURCE_WORKTREE="$REPO_ROOT"
+fi
+
+SOURCE_WORKTREE="$(cd "$SOURCE_WORKTREE" && pwd -P)"
+
+if [ -z "${SESSION_LOG// }" ]; then
+  CURRENT_BRANCH="$(git -C "$SOURCE_WORKTREE" branch --show-current)"
+  if ! SESSION_ID="$(chat_session_id_from_branch "$CURRENT_BRANCH")"; then
+    echo "ERROR: --session-log is required when the source worktree is not on a chat branch." >&2
+    exit 1
+  fi
+  SESSION_LOG="$(chat_log_file_for_session "$SESSION_ID")"
+fi
+
+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
+
+TARGET_BRANCH="$(chat_worktree_metadata_value "$SESSION_LOG" "branch")"
+if [ -z "${TARGET_BRANCH// }" ]; then
+  echo "ERROR: session log is missing branch metadata: $SESSION_LOG" >&2
+  exit 1
+fi
+
+case "$TARGET_BRANCH" in
+  chat/*) ;;
+  *)
+    echo "ERROR: session branch is not a chat branch: $TARGET_BRANCH" >&2
+    exit 1
+    ;;
+esac
+
+TARGET_WORKTREE="$(chat_worktree_metadata_value "$SESSION_LOG" "worktree")"
+if [ -z "${TARGET_WORKTREE// }" ]; then
+  TARGET_WORKTREE="$(chat_worktree_path_for_branch "$REPO_ROOT" "$TARGET_BRANCH")"
+fi
+
+case "$TARGET_WORKTREE" in
+  /*) ;;
+  *) TARGET_WORKTREE="$REPO_ROOT/$TARGET_WORKTREE" ;;
+esac
+
+if [ ! -d "$TARGET_WORKTREE" ]; then
+  echo "ERROR: chat-owned worktree is missing: $TARGET_WORKTREE" >&2
+  echo "Run scripts/00.chat/worktree/ensure-chat-worktree/script.sh first." >&2
+  exit 1
+fi
+
+TARGET_WORKTREE="$(cd "$TARGET_WORKTREE" && pwd -P)"
+
+if [ "$SOURCE_WORKTREE" = "$TARGET_WORKTREE" ]; then
+  echo "ERROR: source worktree and chat-owned worktree are the same path." >&2
+  echo "Normal task work should be staged directly in the chat-owned worktree." >&2
+  exit 1
+fi
+
+if ! git -C "$TARGET_WORKTREE" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  echo "ERROR: chat-owned worktree path is not a git worktree: $TARGET_WORKTREE" >&2
+  exit 1
+fi
+
+TARGET_CURRENT_BRANCH="$(git -C "$TARGET_WORKTREE" branch --show-current)"
+if [ "$TARGET_CURRENT_BRANCH" != "$TARGET_BRANCH" ]; then
+  echo "ERROR: chat-owned worktree is on '$TARGET_CURRENT_BRANCH', expected '$TARGET_BRANCH': $TARGET_WORKTREE" >&2
+  exit 1
+fi
+
+if [ -n "$(git -C "$TARGET_WORKTREE" status --porcelain)" ]; then
+  echo "ERROR: chat-owned worktree is dirty; refusing to import over existing work." >&2
+  echo "Commit, checkpoint, or inspect the target worktree before recovery import." >&2
+  exit 1
+fi
+
+import_path() {
+  local path="$1"
+  local source_path="$SOURCE_WORKTREE/$path"
+  local target_path="$TARGET_WORKTREE/$path"
+  local target_parent
+
+  if [ -e "$source_path" ] || [ -L "$source_path" ]; then
+    target_parent="$(dirname "$target_path")"
+    mkdir -p "$target_parent"
+    rm -rf "$target_path"
+    cp -a "$source_path" "$target_path"
+    git -C "$TARGET_WORKTREE" add -A -- "$path"
+  else
+    git -C "$TARGET_WORKTREE" rm -r --ignore-unmatch -- "$path" >/dev/null 2>&1 || true
+  fi
+}
+
+for path in "$@"; do
+  import_path "$path"
+done
+
+echo "Imported active worktree paths into chat-owned worktree:"
+printf '%s\n' "$@"
+echo "Target worktree: $TARGET_WORKTREE"

package/scripts/00.chat/recovery/import-active-paths-to-chat-worktree/smoke-test.sh

@@ -0,0 +1,162 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# agentic-artifact:
+#   schema: agentic-artifact/v2
+#   id: chat.script.recovery.import-active-paths-to-chat-worktree.smoke-test
+#   version: 1
+#   status: active
+#   layer: 00.chat
+#   domain: recovery
+#   disciplines:
+#   - agentic
+#   kind: script
+#   purpose: Smoke test recovery import from an active worktree into a chat-owned worktree.
+#   portability:
+#     class: reusable
+#     targets:
+#     - llm-workbench
+#   used_by:
+#   - id: chat.script.recovery.import-active-paths-to-chat-worktree
+#     path: scripts/00.chat/recovery/import-active-paths-to-chat-worktree/script.sh
+#   effects:
+#   - branches
+#   - commits
+#   - worktrees
+#   - writes-files
+
+SOURCE_ROOT="$(git rev-parse --show-toplevel)"
+TMP_ROOT="$(mktemp -d "${TMPDIR:-/tmp}/import-active-paths-smoke.XXXXXX")"
+
+cleanup() {
+  rm -rf "$TMP_ROOT"
+}
+
+trap cleanup EXIT
+
+fail() {
+  echo "ERROR: $*" >&2
+  exit 1
+}
+
+assert_file_equals() {
+  local file="$1"
+  local expected="$2"
+  local actual
+
+  actual="$(cat "$file")"
+  if [ "$actual" != "$expected" ]; then
+    fail "expected $file to contain '$expected', got '$actual'"
+  fi
+}
+
+REPO="$TMP_ROOT/repo"
+mkdir -p \
+  "$REPO/scripts/00.chat/recovery/import-active-paths-to-chat-worktree" \
+  "$REPO/scripts/00.chat/session-log/paths" \
+  "$REPO/scripts/00.chat/worktree/paths"
+
+cp "$SOURCE_ROOT/scripts/00.chat/recovery/import-active-paths-to-chat-worktree/script.sh" \
+  "$REPO/scripts/00.chat/recovery/import-active-paths-to-chat-worktree/script.sh"
+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"
+
+git -C "$REPO" init -q -b main
+git -C "$REPO" config user.name "Smoke Test"
+git -C "$REPO" config user.email "smoke@example.invalid"
+
+mkdir -p "$REPO/docs"
+printf 'base\n' > "$REPO/docs/kept.txt"
+printf 'delete me\n' > "$REPO/docs/remove-me.txt"
+git -C "$REPO" add \
+  docs/kept.txt \
+  docs/remove-me.txt \
+  scripts/00.chat/recovery/import-active-paths-to-chat-worktree/script.sh \
+  scripts/00.chat/session-log/paths/lib.sh \
+  scripts/00.chat/worktree/paths/lib.sh
+git -C "$REPO" commit -q -m "initial"
+
+SESSION_ID="2026-06-19-21-00-import-smoke"
+SESSION_BRANCH="chat/$SESSION_ID"
+SESSION_DIR="$REPO/commitLogs/2026/jun/19/$SESSION_ID"
+SESSION_LOG="$SESSION_DIR/README.md"
+WORKTREE_ROOT="$TMP_ROOT/worktrees"
+WORKTREE_PATH="$WORKTREE_ROOT/chat_${SESSION_ID}-$(printf '%s' "$SESSION_BRANCH" | cksum | awk '{print $1}')"
+
+mkdir -p "$SESSION_DIR"
+cat > "$SESSION_LOG" <<EOF
+# Chat Session: import smoke
+
+<!-- agentic-session
+id: $SESSION_ID
+task: import smoke
+branch: $SESSION_BRANCH
+worktree: $WORKTREE_PATH
+layer: 00.chat
+mode: implementation
+workflow: .agentic/00.chat/workflows/chat-start.md
+status: ready
+raised_at_utc: 2026-06-19T20:00:00Z
+-->
+EOF
+
+git -C "$REPO" add "$SESSION_LOG"
+git -C "$REPO" commit -q -m "add session log"
+git -C "$REPO" branch "$SESSION_BRANCH"
+git -C "$REPO" worktree add --quiet "$WORKTREE_PATH" "$SESSION_BRANCH"
+
+printf 'changed in active\n' > "$REPO/docs/kept.txt"
+rm "$REPO/docs/remove-me.txt"
+mkdir -p "$REPO/docs/new-dir"
+printf 'new file\n' > "$REPO/docs/new-dir/new.txt"
+
+(
+  cd "$REPO"
+  AGENTIC_CHAT_WORKTREE_ROOT="$WORKTREE_ROOT" \
+    bash scripts/00.chat/recovery/import-active-paths-to-chat-worktree/script.sh \
+      --session-log "$SESSION_LOG" \
+      --source-worktree "$REPO" \
+      -- docs/kept.txt docs/remove-me.txt docs/new-dir
+)
+
+assert_file_equals "$WORKTREE_PATH/docs/kept.txt" "changed in active"
+assert_file_equals "$WORKTREE_PATH/docs/new-dir/new.txt" "new file"
+
+if [ -e "$WORKTREE_PATH/docs/remove-me.txt" ]; then
+  fail "deleted active path still exists in chat-owned worktree"
+fi
+
+if ! git -C "$WORKTREE_PATH" diff --cached --name-only | grep -qx 'docs/kept.txt'; then
+  fail "changed file was not staged"
+fi
+
+if ! git -C "$WORKTREE_PATH" diff --cached --name-only | grep -qx 'docs/remove-me.txt'; then
+  fail "deleted file was not staged"
+fi
+
+if ! git -C "$WORKTREE_PATH" diff --cached --name-only | grep -qx 'docs/new-dir/new.txt'; then
+  fail "new file was not staged"
+fi
+
+set +e
+(
+  cd "$REPO"
+  bash scripts/00.chat/recovery/import-active-paths-to-chat-worktree/script.sh \
+    --session-log "$SESSION_LOG" \
+    --source-worktree "$REPO" \
+    -- /absolute/path
+) > "$TMP_ROOT/unsafe.out" 2> "$TMP_ROOT/unsafe.err"
+UNSAFE_STATUS="$?"
+set -e
+
+if [ "$UNSAFE_STATUS" -eq 0 ]; then
+  fail "unsafe absolute path was not rejected"
+fi
+
+if ! grep -q "path must be a repository-relative path" "$TMP_ROOT/unsafe.err"; then
+  fail "unsafe path rejection message was not emitted"
+fi
+
+echo "import active paths recovery smoke test passed."

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

@@ -0,0 +1,30 @@
+<!-- agentic-artifact:
+  schema: agentic-artifact/v2
+  id: chat.script.reporting.readme
+  version: 1
+  status: active
+  layer: 00.chat
+  domain: reporting
+  disciplines:
+  - agentic
+  kind: script-domain-readme
+  purpose: Explain on-demand chat reporting scripts.
+  portability:
+    class: required
+    targets:
+    - llm-workbench
+  used_by:
+  - id: chat.workflows.chat-reporting
+    path: .agentic/00.chat/workflows/chat-reporting.md
+  - id: chat.script.reporting.generate-commit-log-summary.readme
+    path: scripts/00.chat/reporting/generate-commit-log-summary/README.md
+-->
+# Reporting Scripts
+
+Reporting scripts summarize chat branches, worktrees, and session logs on
+demand. They do not create always-generated aggregate artifacts.
+
+The durable source evidence is each individual session log under `commitLogs/`.
+Reports should be reproducible from those logs and should avoid reviving the
+retired tracked `commitLogs/README.md` summary.
+

package/scripts/00.chat/reporting/generate-commit-log-summary/README.md

@@ -0,0 +1,35 @@
+<!-- agentic-artifact:
+  schema: agentic-artifact/v2
+  id: chat.script.reporting.generate-commit-log-summary.readme
+  version: 1
+  status: active
+  layer: 00.chat
+  domain: reporting
+  disciplines:
+  - agentic
+  kind: capability-readme
+  purpose: Explain on-demand aggregate summaries from chat session logs.
+  portability:
+    class: required
+    targets:
+    - llm-workbench
+  used_by:
+  - id: chat.skills.session-summary
+    path: .agentic/00.chat/skills/session-summary.md
+  - id: chat.script.reporting.generate-commit-log-summary
+    path: scripts/00.chat/reporting/generate-commit-log-summary/script.sh
+-->
+# Generate Commit Log Summary
+
+`script.sh` builds an aggregate summary from individual chat session logs.
+
+By default it prints the summary. With `--output <path>`, it writes to an
+explicit on-demand artifact path. It must not recreate the retired tracked
+`commitLogs/README.md` file.
+
+Use this capability when a human asks for a session overview, metrics summary,
+or chat history report. The individual session logs remain the durable source.
+
+`smoke-test.sh` verifies that summary generation works and that the retired
+aggregate artifact is not written by default.
+