llm-wb 0.1.0-beta.0

package/scripts/00.chat/reporting/generate-commit-log-summary/script.sh

@@ -0,0 +1,299 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# agentic-artifact:
+#   schema: agentic-artifact/v2
+#   id: chat.script.reporting.generate-commit-log-summary
+#   version: 1
+#   status: active
+#   layer: 00.chat
+#   domain: reporting
+#   disciplines:
+#   - agentic
+#   kind: script
+#   purpose: Generate 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.workflows.chat-reporting
+#     path: .agentic/00.chat/workflows/chat-reporting.md
+#   effects:
+#   - read-only
+#   - writes-files
+
+usage() {
+  cat <<'EOF'
+Usage:
+  generate-commit-log-summary.sh [--print|--output <path>]
+
+Prints an aggregate summary from individual chat session logs.
+Use --output to write the summary to an explicit on-demand artifact path.
+Do not write commitLogs/README.md.
+EOF
+}
+
+OUTPUT_PATH=""
+MODE="print"
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --print)
+      MODE="print"
+      shift
+      ;;
+    --output)
+      if [ $# -lt 2 ]; then
+        usage >&2
+        exit 2
+      fi
+      MODE="output"
+      OUTPUT_PATH="$2"
+      shift 2
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      usage >&2
+      exit 2
+      ;;
+  esac
+done
+
+if [ "$OUTPUT_PATH" = "commitLogs/README.md" ]; then
+  echo "ERROR: commitLogs/README.md is not maintained as an aggregate artifact." >&2
+  echo "Write on-demand summaries somewhere else, such as /tmp/chat-summary.md." >&2
+  exit 1
+fi
+
+node - "$MODE" "$OUTPUT_PATH" <<'NODE'
+const fs = require('fs');
+const path = require('path');
+
+const mode = process.argv[2];
+const outputPath = process.argv[3];
+const root = 'commitLogs';
+const retiredOutputPath = path.join(root, 'README.md');
+
+function walk(dir) {
+  if (!fs.existsSync(dir)) {
+    return [];
+  }
+
+  return fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+    const entryPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      return walk(entryPath);
+    }
+    if (entry.isFile() && entry.name === 'README.md' && entryPath !== retiredOutputPath) {
+      return [entryPath];
+    }
+    return [];
+  });
+}
+
+function metadata(content) {
+  const match = content.match(/<!-- agentic-session\n([\s\S]*?)\n-->/);
+  if (!match) {
+    return {};
+  }
+
+  return Object.fromEntries(
+    match[1].split('\n').map((line) => {
+      const separator = line.indexOf(':');
+      if (separator === -1) {
+        return null;
+      }
+      return [
+        line.slice(0, separator).trim(),
+        line.slice(separator + 1).trim(),
+      ];
+    }).filter(Boolean),
+  );
+}
+
+function parseDurationSeconds(value) {
+  const match = String(value || '').match(/(\d+)s\b/);
+  return match ? Number(match[1]) : null;
+}
+
+function parseTokenCount(value) {
+  const match = String(value || '').match(/^(\d+)\b/);
+  return match ? Number(match[1]) : null;
+}
+
+function parseUsdCost(value) {
+  const match = String(value || '').match(/^USD\s+(\d+(?:\.\d+)?)\b/);
+  return match ? Number(match[1]) : null;
+}
+
+function mean(values) {
+  return values.reduce((sum, value) => sum + value, 0) / values.length;
+}
+
+function standardDeviation(values, average) {
+  const variance = values.reduce((sum, value) => {
+    return sum + ((value - average) ** 2);
+  }, 0) / values.length;
+  return Math.sqrt(variance);
+}
+
+function quantile(sortedValues, q) {
+  if (sortedValues.length === 0) {
+    return null;
+  }
+  if (sortedValues.length === 1) {
+    return sortedValues[0];
+  }
+
+  const position = (sortedValues.length - 1) * q;
+  const lower = Math.floor(position);
+  const upper = Math.ceil(position);
+  const weight = position - lower;
+
+  return sortedValues[lower] * (1 - weight) + sortedValues[upper] * weight;
+}
+
+function metricStats(values) {
+  const valid = values.filter((value) => Number.isFinite(value));
+  if (valid.length === 0) {
+    return {
+      validCount: 0,
+      includedCount: 0,
+      outlierCount: 0,
+      total: null,
+      min: null,
+      max: null,
+      average: null,
+      q1: null,
+      median: null,
+      q3: null,
+    };
+  }
+
+  const average = mean(valid);
+  const sd = standardDeviation(valid, average);
+  const included = sd === 0
+    ? valid
+    : valid.filter((value) => Math.abs(value - average) <= 3 * sd);
+  const sorted = [...included].sort((a, b) => a - b);
+
+  return {
+    validCount: valid.length,
+    includedCount: included.length,
+    outlierCount: valid.length - included.length,
+    total: included.reduce((sum, value) => sum + value, 0),
+    min: sorted[0],
+    max: sorted[sorted.length - 1],
+    average: mean(included),
+    q1: quantile(sorted, 0.25),
+    median: quantile(sorted, 0.5),
+    q3: quantile(sorted, 0.75),
+  };
+}
+
+function formatNumber(value) {
+  if (value === null || value === undefined || Number.isNaN(value)) {
+    return 'n/a';
+  }
+  return Number.isInteger(value) ? String(value) : value.toFixed(2);
+}
+
+function formatUsd(value) {
+  if (value === null || value === undefined || Number.isNaN(value)) {
+    return 'n/a';
+  }
+  if (value > 0 && value < 1) {
+    return `USD ${value.toFixed(4)}`;
+  }
+  return `USD ${value.toFixed(2)}`;
+}
+
+function formatDuration(value) {
+  if (value === null || value === undefined || Number.isNaN(value)) {
+    return 'n/a';
+  }
+
+  const rounded = Math.round(value);
+  const days = Math.floor(rounded / 86400);
+  const hours = Math.floor((rounded % 86400) / 3600);
+  const minutes = Math.floor((rounded % 3600) / 60);
+  const seconds = rounded % 60;
+
+  return `${rounded}s (${String(days).padStart(2, '0')}:` +
+    `${String(hours).padStart(2, '0')}:` +
+    `${String(minutes).padStart(2, '0')}:` +
+    `${String(seconds).padStart(2, '0')})`;
+}
+
+function metricTable(stats, formatter) {
+  return [
+    '| Metric | Value |',
+    '| --- | ---: |',
+    `| Valid chats | ${stats.validCount} |`,
+    `| Included chats | ${stats.includedCount} |`,
+    `| Outliers excluded | ${stats.outlierCount} |`,
+    `| Total | ${formatter(stats.total)} |`,
+    `| Min | ${formatter(stats.min)} |`,
+    `| Max | ${formatter(stats.max)} |`,
+    `| Average | ${formatter(stats.average)} |`,
+    `| Q1 | ${formatter(stats.q1)} |`,
+    `| Median | ${formatter(stats.median)} |`,
+    `| Q3 | ${formatter(stats.q3)} |`,
+  ].join('\n');
+}
+
+const logs = walk(root).sort();
+const records = logs.map((filePath) => {
+  const content = fs.readFileSync(filePath, 'utf8');
+  const data = metadata(content);
+  return {
+    filePath,
+    id: data.id || path.basename(path.dirname(filePath)),
+    durationSeconds: parseDurationSeconds(data.chat_duration),
+    tokens: parseTokenCount(data.estimated_chat_tokens),
+    cost: parseUsdCost(data.estimated_chat_cost),
+  };
+});
+
+const durationStats = metricStats(records.map((record) => record.durationSeconds));
+const tokenStats = metricStats(records.map((record) => record.tokens));
+const costStats = metricStats(records.map((record) => record.cost));
+
+const lines = [
+  '# Commit Log Summary',
+  '',
+  `Total chats: ${records.length}`,
+  '',
+  'Outliers are values more than 3 standard deviations from the mean for each metric.',
+  '',
+  '## Chat Duration',
+  '',
+  metricTable(durationStats, formatDuration),
+  '',
+  '## Estimated Chat Tokens',
+  '',
+  metricTable(tokenStats, formatNumber),
+  '',
+  '## Estimated Chat Cost',
+  '',
+  metricTable(costStats, formatUsd),
+  '',
+];
+
+const output = lines.join('\n');
+
+if (mode === 'print') {
+  process.stdout.write(output);
+  process.exit(0);
+}
+
+fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+fs.writeFileSync(outputPath, output);
+console.log(`Wrote ${outputPath}`);
+NODE

package/scripts/00.chat/reporting/generate-commit-log-summary/smoke-test.sh

@@ -0,0 +1,93 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# agentic-artifact:
+#   schema: agentic-artifact/v2
+#   id: chat.script.reporting.generate-commit-log-summary.smoke-test
+#   version: 1
+#   status: active
+#   layer: 00.chat
+#   domain: validation
+#   disciplines:
+#   - agentic
+#   kind: script
+#   purpose: Smoke test on-demand chat commit log summary generation.
+#   portability:
+#     class: reusable
+#     targets:
+#     - llm-workbench
+#   used_by:
+#   - id: chat.workflows.chat-reporting
+#     path: .agentic/00.chat/workflows/chat-reporting.md
+#   effects:
+#   - writes-files
+
+fail() {
+  echo "FAIL: $*" >&2
+  exit 1
+}
+
+SOURCE_ROOT="$(git rev-parse --show-toplevel)"
+TMP_ROOT="$(mktemp -d "${TMPDIR:-/tmp}/commit-log-summary-smoke.XXXXXX")"
+
+cleanup() {
+  rm -rf "$TMP_ROOT"
+}
+
+trap cleanup EXIT
+
+REPO="$TMP_ROOT/repo"
+mkdir -p "$REPO/scripts/00.chat/reporting/generate-commit-log-summary" "$REPO/commitLogs/2026/jun/17/test-chat"
+cp "$SOURCE_ROOT/scripts/00.chat/reporting/generate-commit-log-summary/script.sh" \
+  "$REPO/scripts/00.chat/reporting/generate-commit-log-summary/script.sh"
+
+cat > "$REPO/commitLogs/2026/jun/17/test-chat/README.md" <<'EOF'
+# Chat Session: test-chat
+
+<!-- agentic-session
+id: test-chat
+chat_duration: 42s
+estimated_chat_tokens: 100 tokens
+estimated_chat_cost: USD 0.0030 estimated from estimated_chat_tokens
+-->
+EOF
+
+(
+  cd "$REPO"
+  bash scripts/00.chat/reporting/generate-commit-log-summary/script.sh > "$TMP_ROOT/printed.md"
+  bash scripts/00.chat/reporting/generate-commit-log-summary/script.sh --output "$TMP_ROOT/written.md" >/dev/null
+)
+
+if ! cmp -s "$TMP_ROOT/written.md" "$TMP_ROOT/printed.md"; then
+  fail "printed output did not match explicit output file"
+fi
+
+set +e
+(
+  cd "$REPO"
+  bash scripts/00.chat/reporting/generate-commit-log-summary/script.sh --output commitLogs/README.md
+) >/dev/null 2>"$TMP_ROOT/blocked.err"
+BLOCKED_STATUS="$?"
+set -e
+
+if [ "$BLOCKED_STATUS" -eq 0 ]; then
+  fail "script allowed writing commitLogs/README.md"
+fi
+
+if ! grep -q "not maintained" "$TMP_ROOT/blocked.err"; then
+  fail "script did not explain retired aggregate path"
+fi
+
+if ! grep -q "Estimated Chat Tokens" "$TMP_ROOT/printed.md"; then
+  fail "summary did not use estimated chat token heading"
+fi
+
+if ! grep -q "Estimated Chat Cost" "$TMP_ROOT/printed.md"; then
+  fail "summary did not use estimated chat cost heading"
+fi
+
+if ! grep -q '| Total | USD 0.0030 |' "$TMP_ROOT/printed.md"; then
+  fail "summary did not aggregate estimated chat cost"
+fi
+
+echo "commit log summary smoke test passed."

package/scripts/00.chat/reporting/report-chat-workspaces/README.md

@@ -0,0 +1,32 @@
+<!-- agentic-artifact:
+  schema: agentic-artifact/v2
+  id: chat.script.reporting.report-chat-workspaces.readme
+  version: 1
+  status: active
+  layer: 00.chat
+  domain: reporting
+  disciplines:
+  - agentic
+  kind: capability-readme
+  purpose: Explain chat branch and worktree status reporting.
+  portability:
+    class: required
+    targets:
+    - llm-workbench
+  used_by:
+  - id: chat.workflows.chat-cleanup
+    path: .agentic/00.chat/workflows/chat-cleanup.md
+  - id: chat.script.reporting.report-chat-workspaces
+    path: scripts/00.chat/reporting/report-chat-workspaces/script.sh
+-->
+# Report Chat Workspaces
+
+`script.sh` prints a table of local `chat/*` branches, ahead/behind state,
+recorded log head state, and worktree path.
+
+Use this before cleanup or promotion when a human needs to understand which
+chat branches are active, stale, missing logs, or checked out elsewhere.
+
+The script is read-only. It does not delete branches, clean worktrees, merge,
+or push.
+

package/scripts/00.chat/reporting/report-chat-workspaces/script.sh

@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# agentic-artifact:
+#   schema: agentic-artifact/v2
+#   id: chat.script.reporting.report-chat-workspaces
+#   version: 1
+#   status: active
+#   layer: 00.chat
+#   domain: reporting
+#   disciplines:
+#   - agentic
+#   kind: script
+#   purpose: Report chat branches, log head state, and worktree status.
+#   portability:
+#     class: required
+#     targets:
+#     - llm-workbench
+#   used_by:
+#   - id: chat.workflows.chat-cleanup
+#     path: .agentic/00.chat/workflows/chat-cleanup.md
+#   - id: chat.workflows.chat-promote-to-main
+#     path: .agentic/00.chat/workflows/chat-promote-to-main.md
+#   effects:
+#   - read-only
+
+BASE_BRANCH="${1:-main}"
+
+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 ! git -C "$REPO_ROOT" show-ref --verify --quiet "refs/heads/${BASE_BRANCH}"; then
+  echo "ERROR: base branch does not exist: $BASE_BRANCH" >&2
+  exit 1
+fi
+
+printf 'Base branch: %s\n' "$BASE_BRANCH"
+printf '%-64s %-8s %-8s %-8s %-10s %s\n' "branch" "ahead" "behind" "status" "log-head" "worktree"
+
+git -C "$REPO_ROOT" branch --format='%(refname:short)' | while IFS= read -r branch; do
+  case "$branch" in
+    chat/*) ;;
+    *) continue ;;
+  esac
+
+  session_id="${branch#chat/}"
+  log_file="$(chat_log_file_for_session "$session_id")"
+  branch_head="$(git -C "$REPO_ROOT" rev-parse --short "$branch")"
+  recorded_head=""
+  log_head_state="missing"
+
+  if [ -f "$log_file" ]; then
+    recorded_head="$(chat_worktree_metadata_value "$log_file" "latest_commit_sha")"
+    if [ -z "${recorded_head// }" ]; then
+      log_head_state="unrecorded"
+    elif [ "${recorded_head:0:7}" = "$branch_head" ]; then
+      log_head_state="matches"
+    else
+      log_head_state="differs"
+    fi
+  fi
+
+  ahead="$(git -C "$REPO_ROOT" rev-list --count "${BASE_BRANCH}..${branch}")"
+  behind="$(git -C "$REPO_ROOT" rev-list --count "${branch}..${BASE_BRANCH}")"
+  worktree_path="$(chat_worktree_path_for_branch "$REPO_ROOT" "$branch")"
+  status="absent"
+
+  if [ -d "$worktree_path/.git" ] || git -C "$worktree_path" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    if [ -z "$(git -C "$worktree_path" status --porcelain)" ]; then
+      status="clean"
+    else
+      status="dirty"
+    fi
+  fi
+
+  printf '%-64s %-8s %-8s %-8s %-10s %s\n' "$branch" "$ahead" "$behind" "$status" "$log_head_state" "$worktree_path"
+done

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

@@ -0,0 +1,33 @@
+<!-- agentic-artifact:
+  schema: agentic-artifact/v2
+  id: chat.script.session-log.readme
+  version: 1
+  status: active
+  layer: 00.chat
+  domain: session-log
+  disciplines:
+  - agentic
+  kind: script-domain-readme
+  purpose: Explain session-log scripts for durable chat evidence.
+  portability:
+    class: required
+    targets:
+    - llm-workbench
+  used_by:
+  - id: chat.checklists.before-commit
+    path: .agentic/00.chat/checklists/before-commit.md
+  - id: chat.script.session-log.record-chat-commit.readme
+    path: scripts/00.chat/session-log/record-chat-commit/README.md
+-->
+# Session Log Scripts
+
+Session-log scripts read and update the durable evidence for a chat. The
+session log records task intent, branch/worktree metadata, workflow routing,
+activity, decisions, issues, commits, conflicts, and metrics.
+
+These scripts are part of why chats are auditable. They should update only the
+current chat's log unless a workflow explicitly says otherwise.
+
+The helper libraries in this domain provide shared path and metadata parsing
+for other chat capabilities.
+

package/scripts/00.chat/session-log/check-commit-prerequisites/README.md

@@ -0,0 +1,89 @@
+<!-- agentic-artifact:
+  schema: agentic-artifact/v2
+  id: chat.script.session-log.check-commit-prerequisites.readme
+  version: 1
+  status: active
+  layer: 00.chat
+  domain: session-log
+  disciplines:
+  - agentic
+  kind: capability-readme
+  purpose: Explain how commit prerequisite checks verify workflow and gate references
+    before chat commits.
+  portability:
+    class: required
+    targets:
+    - llm-workbench
+  used_by:
+  - id: chat.script.session-log.check-commit-prerequisites
+    path: scripts/00.chat/session-log/check-commit-prerequisites/script.sh
+  - id: chat.script.session-log.check-commit-prerequisites.smoke-test
+    path: scripts/00.chat/session-log/check-commit-prerequisites/smoke-test.sh
+  - id: harness.architecture.adr.0017-organize-scripts-by-owner-domain-and-capability
+-->
+# Check Commit Prerequisites
+
+`script.sh` verifies that the current chat session points at real governance
+artifacts before a task commit proceeds.
+
+It is a structural readiness check. It does not decide whether the code change
+is good. It checks that the session log, declared workflow, canonical checklist,
+and referenced gate scripts are present so the commit boundary is governed by
+real files rather than stale documentation.
+
+## Mental Model
+
+A chat session is only committable if its process map still resolves.
+
+The session log names a workflow. The workflow and before-commit checklist name
+scripts that should exist. If any of those links are broken, the agent might be
+following a workflow that cannot actually run.
+
+This gate catches that problem before the task commit.
+
+## Checks
+
+The script verifies:
+
+- current branch is a `chat/*` branch
+- matching session log exists
+- session metadata includes a `workflow`
+- declared workflow file exists
+- canonical `.agentic/00.chat/checklists/before-commit.md` exists
+- executable script references in the workflow and checklist point to real
+  `.sh` files
+
+Directory prose such as `scripts/00.chat/` is ignored; only script-looking
+references ending in `.sh` are treated as gate references.
+
+## What This Does Not Do
+
+- It does not run every referenced gate.
+- It does not inspect code quality.
+- It does not stage, commit, merge, or push.
+- It does not validate ADR disposition content.
+- It does not replace `prepare-chat-session-before-commit`; it is one gate that
+  the readiness coordinator runs.
+
+## Validation
+
+`smoke-test.sh` builds a throwaway chat repo and verifies that:
+
+- a valid workflow/checklist setup passes
+- prose directory references are not mistaken for missing scripts
+
+Run the canonical smoke test with:
+
+```bash
+bash scripts/00.chat/session-log/check-commit-prerequisites/smoke-test.sh
+```
+
+## Compatibility
+
+The old shared path remains available:
+
+```bash
+scripts/00.chat/session-log/check-commit-prerequisites/script.sh
+```
+
+That file is now a compatibility wrapper around the canonical implementation.