llm-wb 0.1.0-beta.0

package/scripts/00.chat/session-log/checkpoint-chat-session-log/script.sh

@@ -0,0 +1,126 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# agentic-artifact:
+#   schema: agentic-artifact/v2
+#   id: chat.script.session-log.checkpoint-chat-session-log
+#   version: 1
+#   status: active
+#   layer: 00.chat
+#   domain: session-log
+#   disciplines:
+#   - agentic
+#   kind: script
+#   purpose: Commit only the current chat session log as bookkeeping.
+#   portability:
+#     class: required
+#     targets:
+#     - llm-workbench
+#   used_by:
+#   - id: chat.script.session-log.checkpoint-chat-session-log.readme
+#     path: scripts/00.chat/session-log/checkpoint-chat-session-log/README.md
+#   effects:
+#   - stages-files
+#   - commits
+
+# shellcheck source=../paths/lib.sh
+source "scripts/00.chat/session-log/paths/lib.sh"
+
+usage() {
+  cat <<'EOF'
+Usage:
+  checkpoint-chat-session-log.sh [--dry-run] [message]
+
+Commits only the current chat session log as a narrow bookkeeping checkpoint.
+Use after record-chat-commit.sh leaves the session log dirty.
+EOF
+}
+
+DRY_RUN="no"
+
+if [ $# -gt 2 ]; then
+  usage >&2
+  exit 2
+fi
+
+if [ "${1:-}" = "--dry-run" ]; then
+  DRY_RUN="yes"
+  shift
+fi
+
+if [ $# -gt 1 ]; then
+  usage >&2
+  exit 2
+fi
+
+COMMIT_MESSAGE="${1:-chore(session): checkpoint chat log}"
+
+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
+
+STAGED_FILES="$(git diff --cached --name-only)"
+
+if [ -n "${STAGED_FILES// }" ]; then
+  MIXED_STAGED="$(printf '%s\n' "$STAGED_FILES" | awk \
+    -v log_file="$LOG_FILE" \
+    '$0 != log_file')"
+  if [ -n "${MIXED_STAGED// }" ]; then
+    echo "ERROR: cannot checkpoint session bookkeeping with other staged files:" >&2
+    printf '%s\n' "$MIXED_STAGED" >&2
+    exit 1
+  fi
+fi
+
+MIXED_DIRTY="$(
+  {
+    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 [ -n "${MIXED_DIRTY// }" ]; then
+  echo "ERROR: cannot checkpoint session bookkeeping with other dirty files:" >&2
+  printf '%s\n' "$MIXED_DIRTY" >&2
+  exit 1
+fi
+
+LOG_HAS_CHANGES="no"
+
+if ! git ls-files --error-unmatch "$LOG_FILE" >/dev/null 2>&1 ||
+   ! git diff --quiet -- "$LOG_FILE" ||
+   ! git diff --cached --quiet -- "$LOG_FILE"; then
+  LOG_HAS_CHANGES="yes"
+fi
+
+if [ "$LOG_HAS_CHANGES" = "no" ]; then
+  echo "No session bookkeeping changes to checkpoint."
+  exit 0
+fi
+
+if [ "$DRY_RUN" = "yes" ]; then
+  echo "Would checkpoint chat session bookkeeping:"
+  echo "Message: $COMMIT_MESSAGE"
+  echo "Log: $LOG_FILE"
+  exit 0
+fi
+
+git add -- "$LOG_FILE"
+git commit -m "$COMMIT_MESSAGE" -- "$LOG_FILE"
+
+echo "Checkpointed chat session bookkeeping:"
+echo "Log: $LOG_FILE"

package/scripts/00.chat/session-log/paths/README.md

@@ -0,0 +1,38 @@
+<!-- agentic-artifact:
+  schema: agentic-artifact/v2
+  id: chat.script.session-log.paths.readme
+  version: 1
+  status: active
+  layer: 00.chat
+  domain: session-log
+  disciplines:
+  - agentic
+  kind: capability-readme
+  purpose: Explain helper functions for chat session log paths and metadata.
+  portability:
+    class: required
+    targets:
+    - llm-workbench
+  used_by:
+  - id: chat.script.session-log.paths.lib
+    path: scripts/00.chat/session-log/paths/lib.sh
+  - id: chat.script.session-log.read-current-chat-log
+    path: scripts/00.chat/session-log/read-current-chat-log/script.sh
+-->
+# Session Log Paths
+
+`lib.sh` provides shell helper functions for converting chat branch names and
+session ids into session-log paths.
+
+The library understands the grouped log layout:
+
+```txt
+commitLogs/<year>/<month>/<day>/<session>/README.md
+```
+
+It also reads metadata values from the `agentic-session` comment block. Scripts
+use these helpers so branch-to-log lookup stays consistent across startup,
+commit gates, reporting, recovery, and cleanup.
+
+This library is read-only. It does not create, modify, stage, or commit logs.
+

package/scripts/00.chat/session-log/paths/lib.sh

@@ -0,0 +1,133 @@
+#!/usr/bin/env bash
+
+# agentic-artifact:
+#   schema: agentic-artifact/v2
+#   id: chat.script.session-log.paths.lib
+#   version: 1
+#   status: active
+#   layer: 00.chat
+#   domain: session-log
+#   disciplines:
+#   - agentic
+#   kind: script
+#   purpose: Provide canonical chat session id and commit log path helper functions.
+#   portability:
+#     class: required
+#     targets:
+#     - llm-workbench
+#   used_by:
+#   - id: chat.script.session-log.read-current-chat-log
+#     path: scripts/00.chat/session-log/read-current-chat-log/script.sh
+#   - id: chat.script.session-log.update-chat-log
+#     path: scripts/00.chat/session-log/update-chat-log/script.sh
+#   effects:
+#   - read-only
+chat_session_id_from_branch() {
+  local branch="$1"
+
+  case "$branch" in
+    chat/*)
+      printf '%s\n' "${branch#chat/}"
+      ;;
+    *)
+      return 1
+      ;;
+  esac
+}
+
+chat_log_month_name() {
+  case "$1" in
+    01) printf 'jan\n' ;;
+    02) printf 'feb\n' ;;
+    03) printf 'mar\n' ;;
+    04) printf 'apr\n' ;;
+    05) printf 'may\n' ;;
+    06) printf 'jun\n' ;;
+    07) printf 'jul\n' ;;
+    08) printf 'aug\n' ;;
+    09) printf 'sep\n' ;;
+    10) printf 'oct\n' ;;
+    11) printf 'nov\n' ;;
+    12) printf 'dec\n' ;;
+    *) return 1 ;;
+  esac
+}
+
+chat_log_grouped_dir_for_session() {
+  local session_id="$1"
+  local year month day month_name
+
+  year="${session_id:0:4}"
+  month="${session_id:5:2}"
+  day="${session_id:8:2}"
+
+  if ! month_name="$(chat_log_month_name "$month")"; then
+    return 1
+  fi
+
+  printf 'commitLogs/%s/%s/%s/%s\n' "$year" "$month_name" "$day" "$session_id"
+}
+
+chat_log_metadata_value() {
+  local log_file="$1"
+  local key="$2"
+
+  sed -n '/<!-- agentic-session/,/-->/p' "$log_file" \
+    | sed '/<!-- agentic-session/d;/-->/d' \
+    | sed -n "s/^${key}: //p" \
+    | head -n 1
+}
+
+chat_log_file_for_session_by_metadata() {
+  local session_id="$1"
+  local branch="chat/${session_id}"
+  local grouped_parent found_file found_count file
+
+  grouped_parent="$(chat_log_grouped_dir_for_session "$session_id")"
+  grouped_parent="${grouped_parent%/*}"
+  found_file=""
+  found_count=0
+
+  if [ -d "$grouped_parent" ]; then
+    while IFS= read -r file; do
+      if [ "$(chat_log_metadata_value "$file" "id")" = "$session_id" ] \
+        || [ "$(chat_log_metadata_value "$file" "branch")" = "$branch" ]; then
+        found_file="$file"
+        found_count=$((found_count + 1))
+      fi
+    done < <(find "$grouped_parent" -mindepth 2 -maxdepth 2 -type f -name README.md | sort)
+  fi
+
+  if [ "$found_count" -eq 1 ]; then
+    printf '%s\n' "$found_file"
+    return 0
+  fi
+
+  return 1
+}
+
+chat_log_file_for_session() {
+  local session_id="$1"
+  local grouped_dir flat_file metadata_file
+
+  grouped_dir="$(chat_log_grouped_dir_for_session "$session_id")"
+  flat_file="commitLogs/${session_id}/README.md"
+
+  if [ -f "${grouped_dir}/README.md" ]; then
+    printf '%s\n' "${grouped_dir}/README.md"
+  elif [ -f "$flat_file" ]; then
+    printf '%s\n' "$flat_file"
+  elif metadata_file="$(chat_log_file_for_session_by_metadata "$session_id")"; then
+    printf '%s\n' "$metadata_file"
+  else
+    printf '%s\n' "${grouped_dir}/README.md"
+  fi
+}
+
+chat_log_dir_for_session() {
+  local session_id="$1"
+  local log_file
+
+  log_file="$(chat_log_file_for_session "$session_id")"
+  printf '%s\n' "${log_file%/README.md}"
+}

package/scripts/00.chat/session-log/prepare-chat-session-before-commit/README.md

@@ -0,0 +1,90 @@
+<!-- agentic-artifact:
+  schema: agentic-artifact/v2
+  id: chat.script.session-log.prepare-chat-session-before-commit.readme
+  version: 1
+  status: active
+  layer: 00.chat
+  domain: session-log
+  disciplines:
+  - agentic
+  kind: capability-readme
+  purpose: Explain the chat commit-boundary readiness check before task commits.
+  portability:
+    class: required
+    targets:
+    - llm-workbench
+  used_by:
+  - id: chat.script.session-log.prepare-chat-session-before-commit
+    path: scripts/00.chat/session-log/prepare-chat-session-before-commit/script.sh
+  - id: harness.architecture.adr.0017-organize-scripts-by-owner-domain-and-capability
+-->
+# Prepare Chat Session Before Commit
+
+`script.sh` is the readiness gate for task commits in a governed chat.
+
+It does not create a commit. It checks whether the current chat session has
+enough process context, clean enough staged state, and complete enough session
+metadata for a task commit to proceed.
+
+## Mental Model
+
+Before a task commit, the harness needs two kinds of confidence:
+
+- the Git state is appropriate for committing from this chat worktree
+- the session log has enough context to explain the work after the commit lands
+
+This helper coordinates those checks. It is deliberately read-only. If anything
+is missing, it stops before the commit boundary so the human and agent can fix
+the session state rather than writing an incomplete audit trail.
+
+## Checks
+
+The script runs shared gates first:
+
+- write-location check
+- commit prerequisite check
+- commit-log deletion check
+- deterministic process drift check for staged files
+- metadata header check for newly staged artifacts
+- governed script command drift check
+- optional repo-provided commit gate when
+  `LLM_WORKBENCH_OPTIONAL_COMMIT_GATE` is set to a repository-relative script
+
+Then it validates the current chat session:
+
+- current branch must be a `chat/*` branch
+- matching session log must exist
+- `## Initial Intent` must be recorded
+- `## Decisions Made` must have a real entry
+- `## ADR Disposition` must have a real entry
+- `ADR needed` must be `yes` or `no`
+- when `ADR needed: yes`, the ADR path must point to an existing file under
+  `docs/harness/architecture/adrs/`
+- when `ADR needed` is `yes` or `no`, the reason must be present
+
+## What This Does Not Do
+
+- It does not stage files.
+- It does not create the task commit.
+- It does not record the task commit in the session log.
+- It does not checkpoint session-log bookkeeping.
+- It does not decide whether an ADR is needed.
+
+## Typical Sequence
+
+1. Run this readiness check.
+2. Commit the task changes.
+3. Run `record-chat-commit` with the task commit SHA and summary.
+4. If only the session log is dirty, run `checkpoint-chat-session-log`.
+
+## Compatibility
+
+The governed runner still approves the old path:
+
+```bash
+scripts/00.chat/session-log/prepare-chat-session-before-commit/script.sh
+```
+
+That file is now a compatibility wrapper around the canonical implementation.
+Checklists should keep using the approved shared path until the governed runner
+allowlist policy is migrated.

package/scripts/00.chat/session-log/prepare-chat-session-before-commit/script.sh

@@ -0,0 +1,145 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# agentic-artifact:
+#   schema: agentic-artifact/v2
+#   id: chat.script.session-log.prepare-chat-session-before-commit
+#   version: 1
+#   status: active
+#   layer: 00.chat
+#   domain: session-log
+#   disciplines:
+#   - agentic
+#   kind: script
+#   purpose: Run commit-boundary gates and session-log readiness checks before task commits.
+#   portability:
+#     class: required
+#     targets:
+#     - llm-workbench
+#   used_by:
+#   - id: chat.script.session-log.prepare-chat-session-before-commit.readme
+#     path: scripts/00.chat/session-log/prepare-chat-session-before-commit/README.md
+#   effects:
+#   - read-only
+
+# shellcheck source=../paths/lib.sh
+source "scripts/00.chat/session-log/paths/lib.sh"
+
+bash scripts/00.chat/worktree/check-write-location/script.sh
+bash scripts/00.chat/session-log/check-commit-prerequisites/script.sh
+bash scripts/00.chat/session-log/check-commitlog-deletions/script.sh
+bash scripts/01.harness/check-deterministic-process-drift.sh --staged
+bash scripts/01.harness/artifact-metadata/check-headers/script.sh --staged-added
+bash scripts/01.harness/check-governed-script-command-drift.sh
+
+OPTIONAL_COMMIT_GATE="${LLM_WORKBENCH_OPTIONAL_COMMIT_GATE:-}"
+
+if [ -n "${OPTIONAL_COMMIT_GATE//[[:space:]]/}" ]; then
+  case "$OPTIONAL_COMMIT_GATE" in
+    /*|../*|*/../*|*/..|..|-*|*$'\n'*|*$'\r'*)
+      echo "ERROR: refused non-repository optional commit gate: $OPTIONAL_COMMIT_GATE" >&2
+      exit 1
+      ;;
+  esac
+
+  if [ ! -f "$OPTIONAL_COMMIT_GATE" ]; then
+    echo "ERROR: optional commit gate does not exist: $OPTIONAL_COMMIT_GATE" >&2
+    exit 1
+  fi
+
+  bash "$OPTIONAL_COMMIT_GATE"
+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
+
+FAILURES=0
+
+fail() {
+  echo "ERROR: $*" >&2
+  FAILURES=$((FAILURES + 1))
+}
+
+section_has_recorded_entry() {
+  local section="$1"
+
+  awk -v section="$section" '
+    $0 == section {
+      in_section = 1
+      next
+    }
+    in_section && /^## / {
+      exit
+    }
+    in_section && $0 != "" && $0 != "- None recorded yet." {
+      found = 1
+    }
+    END {
+      exit found ? 0 : 1
+    }
+  ' "$LOG_FILE"
+}
+
+field_value() {
+  local label="$1"
+  sed -n "s/^${label}: //p" "$LOG_FILE" | tail -n 1
+}
+
+require_section_entry() {
+  local section="$1"
+  local description="$2"
+
+  if ! section_has_recorded_entry "$section"; then
+    fail "$description is still missing in $LOG_FILE"
+  fi
+}
+
+require_section_entry "## Initial Intent" "Initial intent"
+require_section_entry "## Decisions Made" "Decisions made summary"
+require_section_entry "## ADR Disposition" "ADR disposition"
+
+ADR_NEEDED="$(field_value "ADR needed")"
+ADR_PATH="$(field_value "ADR path")"
+ADR_REASON="$(field_value "Reason")"
+
+case "$ADR_NEEDED" in
+  yes)
+    if [ -z "${ADR_PATH// }" ]; then
+      fail "ADR needed is yes, but ADR path is empty"
+    elif [[ "$ADR_PATH" != docs/harness/architecture/adrs/*.md ]]; then
+      fail "ADR path must be under docs/harness/architecture/adrs/: $ADR_PATH"
+    elif [ ! -f "$ADR_PATH" ]; then
+      fail "ADR path does not exist: $ADR_PATH"
+    fi
+
+    if [ -z "${ADR_REASON// }" ]; then
+      fail "ADR needed is yes, but reason is empty"
+    fi
+    ;;
+  no)
+    if [ -z "${ADR_REASON// }" ]; then
+      fail "ADR needed is no, but reason is empty"
+    fi
+    ;;
+  *)
+    fail "ADR needed must be yes or no, got: ${ADR_NEEDED:-missing}"
+    ;;
+esac
+
+if [ "$FAILURES" -gt 0 ]; then
+  echo "Chat session is not ready for commit." >&2
+  exit 1
+fi
+
+echo "Chat session is ready for commit: $LOG_FILE"

package/scripts/00.chat/session-log/read-current-chat-log/README.md

@@ -0,0 +1,44 @@
+<!-- agentic-artifact:
+  schema: agentic-artifact/v2
+  id: chat.script.session-log.read-current-chat-log.readme
+  version: 1
+  status: active
+  layer: 00.chat
+  domain: session-log
+  disciplines:
+  - agentic
+  kind: capability-readme
+  purpose: Explain reading current chat session 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.read-current-chat-log
+    path: scripts/00.chat/session-log/read-current-chat-log/script.sh
+-->
+# Read Current Chat Log
+
+`script.sh` prints the metadata block from the current chat branch's session
+log.
+
+It is useful when a workflow or human needs to inspect the current session id,
+branch, worktree, layer, mode, or workflow without opening the full log.
+
+The script requires the current branch to be a `chat/*` branch and the matching
+session log to exist. It is read-only.
+
+By default, it refuses to print metadata for a session that already has a
+`latest_commit_sha`. That protects new user conversations from accidentally
+continuing an old chat worktree simply because the process started there.
+
+Use:
+
+```bash
+bash scripts/00.chat/session-log/read-current-chat-log/script.sh --allow-recorded-session
+```
+
+only after the user explicitly approves continuing the existing chat session and
+worktree.

package/scripts/00.chat/session-log/read-current-chat-log/script.sh

@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# agentic-artifact:
+#   schema: agentic-artifact/v2
+#   id: chat.script.session-log.read-current-chat-log
+#   version: 1
+#   status: active
+#   layer: 00.chat
+#   domain: session-log
+#   disciplines:
+#   - agentic
+#   kind: script
+#   purpose: Print current chat session metadata from the active chat branch 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.session-log.check-commit-prerequisites.smoke-test
+#     path: scripts/00.chat/session-log/check-commit-prerequisites/smoke-test.sh
+#   effects:
+#   - read-only
+
+# shellcheck source=../paths/lib.sh
+source "scripts/00.chat/session-log/paths/lib.sh"
+
+ALLOW_RECORDED_SESSION="no"
+
+usage() {
+  cat <<'EOF'
+Usage:
+  read-current-chat-log/script.sh [--allow-recorded-session]
+
+Prints current chat session metadata.
+
+By default, refuses to reuse a chat session that already has recorded commits.
+Use --allow-recorded-session only after the user explicitly approves continuing
+the existing chat session and worktree.
+EOF
+}
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --allow-recorded-session)
+      ALLOW_RECORDED_SESSION="yes"
+      shift
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "ERROR: unknown argument: $1" >&2
+      usage >&2
+      exit 2
+      ;;
+  esac
+done
+
+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"
+  exit 1
+fi
+
+LOG_FILE="$(chat_log_file_for_session "$SESSION_ID")"
+
+if [ ! -f "$LOG_FILE" ]; then
+  echo "ERROR: missing chat log: $LOG_FILE"
+  exit 1
+fi
+
+METADATA="$(sed -n '/<!-- agentic-session/,/-->/p' "$LOG_FILE" \
+  | sed '/<!-- agentic-session/d;/-->/d')"
+
+LATEST_COMMIT_SHA="$(printf '%s\n' "$METADATA" | sed -n 's/^latest_commit_sha: //p' | head -n 1)"
+
+if [ -n "${LATEST_COMMIT_SHA// }" ] && [ "$ALLOW_RECORDED_SESSION" != "yes" ]; then
+  echo "ERROR: recorded-session-approval-required"
+  echo "Session: $SESSION_ID"
+  echo "Branch: $BRANCH"
+  echo "Log: $LOG_FILE"
+  echo "Latest commit: $LATEST_COMMIT_SHA"
+  echo "Required action: Ask the user to approve continuing this existing chat/worktree, or start a new chat."
+  exit 3
+fi
+
+printf '%s\n' "$METADATA"