llm-wb 0.1.0-beta.0

package/scripts/00.chat/bootstrap/audit-chat-bootstrap-file-set/README.md

@@ -0,0 +1,39 @@
+<!-- agentic-artifact:
+  schema: agentic-artifact/v2
+  id: chat.script.bootstrap.audit-chat-bootstrap-file-set.readme
+  version: 1
+  status: active
+  layer: 00.chat
+  domain: bootstrap
+  disciplines:
+  - agentic
+  kind: capability-readme
+  purpose: Explain the portable chat bootstrap file-set audit.
+  portability:
+    class: required
+    targets:
+    - llm-workbench
+  used_by:
+  - id: chat.workflows.bootstrap-chat-workbench-repo
+    path: .agentic/00.chat/workflows/bootstrap-chat-workbench-repo.md
+  - id: chat.script.bootstrap.audit-chat-bootstrap-file-set
+    path: scripts/00.chat/bootstrap/audit-chat-bootstrap-file-set/script.sh
+-->
+# Audit Chat Bootstrap File Set
+
+`script.sh` reports the script and support-file set needed to bootstrap the
+portable chat harness into another repository.
+
+The audit starts from public chat commands, chat workflows, shared process
+artifacts, and the governed runner. It follows script references from those
+seed surfaces and separates results into:
+
+- required scripts and support files
+- validation and compatibility candidates
+- unclassified candidates
+
+The audit does not copy files. It is an evidence tool for the bootstrap
+workflow. A clean result means the portable set is understood; it does not mean
+the public repository shell, install script, license, or smoke test has already
+been created.
+

package/scripts/00.chat/bootstrap/audit-chat-bootstrap-file-set/script.sh

@@ -0,0 +1,213 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# agentic-artifact:
+#   schema: agentic-artifact/v2
+#   id: chat.script.bootstrap.audit-chat-bootstrap-file-set
+#   version: 1
+#   status: active
+#   layer: 00.chat
+#   domain: bootstrap
+#   disciplines:
+#   - agentic
+#   kind: script
+#   purpose: Audit the portable chat bootstrap script and support-file set.
+#   portability:
+#     class: required
+#     targets:
+#     - llm-workbench
+#   used_by:
+#   - id: chat.workflows.bootstrap-chat-workbench-repo
+#     path: .agentic/00.chat/workflows/bootstrap-chat-workbench-repo.md
+#   - id: shared.standard.upstream-repo-bootstrap
+#     path: .agentic/shared/standards/upstream-repo-bootstrap.md
+#   - id: harness.script.run-governed-script
+#     path: scripts/01.harness/run-governed-script.sh
+#   effects:
+#   - read-only
+
+usage() {
+  cat <<'EOF'
+Usage:
+  audit-chat-bootstrap-file-set.sh
+
+Reports the script and support-file dependency set for the portable chat
+harness bootstrap.
+
+The audit starts from package chat commands, chat workflows, shared process
+artifacts used by chat startup/commit/promotion, and the governed script runner.
+It then follows script references to produce a required script set and candidate
+unreferenced scripts.
+EOF
+}
+
+if [ "${1:-}" = "-h" ] || [ "${1:-}" = "--help" ]; then
+  usage
+  exit 0
+fi
+
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+cd "$REPO_ROOT"
+
+TMP_DIR="$(mktemp -d "${TMPDIR:-/tmp}/chat-bootstrap-audit.XXXXXX")"
+trap 'rm -rf "$TMP_DIR"' EXIT
+
+SEEDS="$TMP_DIR/seeds.txt"
+SEEN="$TMP_DIR/seen.txt"
+QUEUE="$TMP_DIR/queue.txt"
+NEXT_QUEUE="$TMP_DIR/next-queue.txt"
+SCRIPT_REFS="$TMP_DIR/script-refs.txt"
+MISSING="$TMP_DIR/missing.txt"
+ALL_SCRIPTS="$TMP_DIR/all-scripts.txt"
+REQUIRED="$TMP_DIR/required.txt"
+UNREFERENCED="$TMP_DIR/unreferenced.txt"
+VALIDATION="$TMP_DIR/validation.txt"
+COMPATIBILITY="$TMP_DIR/compatibility.txt"
+UNCLASSIFIED="$TMP_DIR/unclassified.txt"
+
+: > "$SEEDS"
+: > "$SEEN"
+: > "$QUEUE"
+: > "$SCRIPT_REFS"
+: > "$MISSING"
+
+add_if_exists() {
+  local path="$1"
+
+  if [ -e "$path" ]; then
+    printf '%s\n' "$path" >> "$SEEDS"
+  fi
+}
+
+add_tree_if_exists() {
+  local path="$1"
+
+  if [ -d "$path" ]; then
+    find "$path" -type f >> "$SEEDS"
+  fi
+}
+
+add_if_exists "AGENTS.md"
+add_tree_if_exists ".agentic/00.chat"
+add_tree_if_exists ".agentic/shared/standards"
+add_tree_if_exists ".agentic/shared/workflows"
+add_if_exists "package.json"
+add_if_exists "scripts/01.harness/run-governed-script.sh"
+add_if_exists "scripts/01.harness/check-deterministic-process-drift.sh"
+add_tree_if_exists "scripts/01.harness/artifact-metadata"
+add_if_exists "scripts/01.harness/check-artifact-metadata-headers.sh"
+add_if_exists "scripts/01.harness/check-governed-script-command-drift.sh"
+add_if_exists "scripts/01.harness/plan-artifact-path-migration.sh"
+add_if_exists "scripts/01.harness/check-artifact-path-migration.sh"
+
+sort -u "$SEEDS" > "$QUEUE"
+
+extract_script_refs() {
+  local path="$1"
+  local dir
+
+  grep -Eo 'scripts/[A-Za-z0-9._/-]+\.(sh|js|mjs|cjs|tsv|json)' "$path" 2>/dev/null \
+    | grep -E '^scripts/(00\.chat|01\.harness|chat|harness|shared)/' || true
+
+  case "$path" in
+    scripts/*)
+      dir="$(dirname "$path")"
+      grep -Eo 'SCRIPT_DIR/[A-Za-z0-9._/-]+\.(sh|js|mjs|cjs|tsv|json)' "$path" 2>/dev/null \
+        | sed "s#^SCRIPT_DIR/#${dir}/#" || true
+      grep -Eo 'dirname "\$0"\)/[A-Za-z0-9._/-]+\.(sh|js|mjs|cjs|tsv|json)' "$path" 2>/dev/null \
+        | sed "s#^dirname \"\\\$0\")/#${dir}/#" || true
+      ;;
+  esac
+}
+
+while [ -s "$QUEUE" ]; do
+  : > "$NEXT_QUEUE"
+
+  while IFS= read -r path; do
+    [ -n "$path" ] || continue
+    grep -Fxq "$path" "$SEEN" && continue
+    printf '%s\n' "$path" >> "$SEEN"
+
+    if [ ! -f "$path" ]; then
+      printf '%s\n' "$path" >> "$MISSING"
+      continue
+    fi
+
+    while IFS= read -r ref; do
+      [ -n "$ref" ] || continue
+      printf '%s\n' "$ref" >> "$SCRIPT_REFS"
+      if [ -f "$ref" ]; then
+        case "$ref" in
+          scripts/*)
+            if ! grep -Fxq "$ref" "$SEEN"; then
+              printf '%s\n' "$ref" >> "$NEXT_QUEUE"
+            fi
+            ;;
+        esac
+      else
+        printf '%s\n' "$ref" >> "$MISSING"
+      fi
+    done < <(extract_script_refs "$path")
+  done < "$QUEUE"
+
+  sort -u "$NEXT_QUEUE" > "$QUEUE"
+done
+
+find scripts -type f \
+  \( -name '*.sh' -o -name '*.js' -o -name '*.mjs' -o -name '*.cjs' -o -name '*.tsv' -o -name '*.json' \) \
+  | sort -u > "$ALL_SCRIPTS"
+
+{
+  grep '^scripts/' "$SEEN" || true
+  sort -u "$SCRIPT_REFS"
+} | sort -u > "$REQUIRED"
+
+comm -23 "$ALL_SCRIPTS" "$REQUIRED" > "$UNREFERENCED"
+while IFS= read -r path; do
+  [ -n "$path" ] || continue
+  if grep -Eq '^([#[:space:]]*|[[:space:]]*//[[:space:]]*)portability: .*compatibility' "$path"; then
+    printf '%s\n' "$path"
+  fi
+done < "$UNREFERENCED" > "$COMPATIBILITY"
+{
+  grep -E '/smoke-test-[^/]+\.sh$|/smoke-test\.sh$|/with-chat-branch\.sh$' "$UNREFERENCED" || true
+  cat "$COMPATIBILITY"
+} | sort -u > "$VALIDATION"
+comm -23 "$UNREFERENCED" "$VALIDATION" > "$UNCLASSIFIED"
+
+echo "Chat bootstrap script file set audit"
+echo
+echo "Seed surfaces scanned:"
+echo "- AGENTS.md"
+echo "- .agentic/00.chat/"
+echo "- .agentic/shared/standards/"
+echo "- .agentic/shared/workflows/"
+echo "- package.json chat scripts"
+echo "- governed runner and deterministic harness checks"
+echo
+echo "Required scripts and support files:"
+cat "$REQUIRED"
+echo
+echo "Validation and compatibility candidates:"
+if [ -s "$VALIDATION" ]; then
+  cat "$VALIDATION"
+else
+  echo "(none)"
+fi
+echo
+echo "Unclassified candidates:"
+if [ -s "$UNCLASSIFIED" ]; then
+  cat "$UNCLASSIFIED"
+else
+  echo "(none)"
+fi
+
+if [ -s "$MISSING" ]; then
+  echo
+  echo "Missing referenced scripts:" >&2
+  sort -u "$MISSING" >&2
+  exit 1
+fi
+
+echo
+echo "Audit completed."

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

@@ -0,0 +1,30 @@
+<!-- agentic-artifact:
+  schema: agentic-artifact/v2
+  id: chat.script.closeout.readme
+  version: 1
+  status: active
+  layer: 00.chat
+  domain: closeout
+  disciplines:
+  - agentic
+  kind: script-domain-readme
+  purpose: Explain closeout scripts that prepare governed end-of-chat prompts.
+  portability:
+    class: required
+    targets:
+    - llm-workbench
+  used_by:
+  - id: chat.commands.readme
+    path: .agentic/00.chat/commands/README.md
+  - id: chat.script.closeout.build-closeout-prompt.readme
+    path: scripts/00.chat/closeout/build-closeout-prompt/README.md
+-->
+# Closeout Scripts
+
+Closeout scripts prepare the handoff from active work to a final agent turn.
+They do not commit or merge work by themselves. Instead, they build the prompt
+that tells the next agent how to inspect the current chat, run required gates,
+commit approved work, and report the result.
+
+This keeps terminal shortcuts convenient without hiding approval boundaries.
+

package/scripts/00.chat/closeout/build-closeout-prompt/README.md

@@ -0,0 +1,35 @@
+<!-- agentic-artifact:
+  schema: agentic-artifact/v2
+  id: chat.script.closeout.build-closeout-prompt.readme
+  version: 1
+  status: active
+  layer: 00.chat
+  domain: closeout
+  disciplines:
+  - agentic
+  kind: capability-readme
+  purpose: Explain how the chat closeout prompt is built and handed to terminal users.
+  portability:
+    class: required
+    targets:
+    - llm-workbench
+  used_by:
+  - id: chat.script.closeout.build-closeout-prompt
+    path: scripts/00.chat/closeout/build-closeout-prompt/script.sh
+  - id: chat.script.command.close
+    path: scripts/00.chat/command/close/script.sh
+-->
+# Build Closeout Prompt
+
+`script.sh` builds the governed prompt used when a human runs the public close
+command. The prompt is meant for the next agent turn: it asks the agent to
+inspect the chat worktree, run the right gates, commit approved work, and
+record the commit.
+
+The script tries to copy the prompt to the clipboard for terminal convenience
+and prints it when clipboard copy is unavailable. Clipboard behavior is not the
+governance contract; the prompt content is.
+
+This capability does not stage files, commit, merge, push, or decide whether
+work is complete.
+

package/scripts/00.chat/closeout/build-closeout-prompt/script.sh

@@ -0,0 +1,124 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# agentic-artifact:
+#   schema: agentic-artifact/v2
+#   id: chat.script.closeout.build-closeout-prompt
+#   version: 1
+#   status: active
+#   layer: 00.chat
+#   domain: closeout
+#   disciplines:
+#   - agentic
+#   kind: script
+#   purpose: Build and copy or print the governed chat closeout prompt.
+#   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:
+#   - read-only
+
+# shellcheck source=../../session-log/paths/lib.sh
+source "scripts/00.chat/session-log/paths/lib.sh"
+
+print_prompt() {
+  echo
+  echo "Paste this into Codex / Claude / Mistral:"
+  echo "$CLOSE_PROMPT"
+}
+
+copy_prompt_with_retry() {
+  local label="$1"
+  shift
+
+  local attempt=1
+  while [ "$attempt" -le 2 ]; do
+    if printf '%s' "$CLOSE_PROMPT" | "$@"; then
+      echo "Copied closeout prompt to clipboard."
+      return 0
+    fi
+
+    if [ "$attempt" -lt 2 ]; then
+      echo "Clipboard copy via ${label} failed; retrying..." >&2
+      sleep 1
+    fi
+
+    attempt=$((attempt + 1))
+  done
+
+  echo "WARNING: Clipboard copy via ${label} failed; printing prompt instead." >&2
+  return 1
+}
+
+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
+
+TASK="$(chat_log_metadata_value "$LOG_FILE" "task")"
+WORKTREE="$(chat_log_metadata_value "$LOG_FILE" "worktree")"
+LAYER="$(chat_log_metadata_value "$LOG_FILE" "layer")"
+MODE="$(chat_log_metadata_value "$LOG_FILE" "mode")"
+
+WORKTREE="${WORKTREE:-$(pwd)}"
+LAYER="${LAYER:-chat}"
+MODE="${MODE:-implementation}"
+
+CLOSE_PROMPT="Task: close this chat by committing approved work if needed and merging the chat branch to local main
+Session log: ${LOG_FILE}
+Chat branch: ${BRANCH}
+Chat worktree: ${WORKTREE}
+Original task: ${TASK}
+Layer: chat
+Mode: implementation
+Workflow: .agentic/00.chat/workflows/chat-promote-to-main.md
+
+Default mode: read-only until I grant each required approval.
+
+Use the current session log as the first source of truth.
+If there is uncommitted task work, follow .agentic/00.chat/workflows/chat-commit.md and .agentic/00.chat/checklists/before-commit.md.
+Ask for explicit approval before creating any task commit.
+After any task commit, record it with:
+bash scripts/01.harness/run-governed-script.sh --approved-action scripts/00.chat/session-log/record-chat-commit/script.sh <sha> <message> <summary> [adr-impact]
+
+Then follow .agentic/00.chat/workflows/chat-promote-to-main.md for local convergence.
+Run the required gates and verification before merging.
+Ask for explicit approval before merging into local main.
+Do not push to origin unless I explicitly approve a separate push.
+
+If governance is missing or state is ambiguous, stop and explain the gap."
+
+case "${CHAT_COPY_PROMPT:-copy}" in
+  skip)
+    print_prompt
+    ;;
+  copy)
+    if command -v clip.exe >/dev/null 2>&1; then
+      copy_prompt_with_retry "clip.exe" clip.exe || print_prompt
+    elif command -v xclip >/dev/null 2>&1; then
+      copy_prompt_with_retry "xclip" xclip -selection clipboard || print_prompt
+    else
+      print_prompt
+    fi
+    ;;
+  *)
+    echo "ERROR: invalid CHAT_COPY_PROMPT value: ${CHAT_COPY_PROMPT}" >&2
+    echo "Use copy or skip." >&2
+    exit 2
+    ;;
+esac

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

@@ -0,0 +1,31 @@
+<!-- agentic-artifact:
+  schema: agentic-artifact/v2
+  id: chat.script.command.readme
+  version: 1
+  status: active
+  layer: 00.chat
+  domain: command
+  disciplines:
+  - agentic
+  kind: script-domain-readme
+  purpose: Explain canonical chat command entrypoints.
+  portability:
+    class: required
+    targets:
+    - llm-workbench
+  used_by:
+  - id: chat.commands.readme
+    path: .agentic/00.chat/commands/README.md
+  - id: chat.script.command.dispatcher.readme
+    path: scripts/00.chat/command/dispatcher/README.md
+-->
+# Command Scripts
+
+Command scripts are the canonical implementation behind public `npm run chat:*`
+shortcuts. They keep the human command surface stable while allowing the actual
+capabilities to live in domain folders such as `startup`, `closeout`, or
+`reporting`.
+
+The command domain is mostly routing. A command entrypoint should delegate to a
+capability script rather than duplicating the capability's logic.
+

package/scripts/00.chat/command/close/README.md

@@ -0,0 +1,30 @@
+<!-- agentic-artifact:
+  schema: agentic-artifact/v2
+  id: chat.script.command.close.readme
+  version: 1
+  status: active
+  layer: 00.chat
+  domain: command
+  disciplines:
+  - agentic
+  kind: capability-readme
+  purpose: Explain the public chat close command entrypoint.
+  portability:
+    class: required
+    targets:
+    - llm-workbench
+  used_by:
+  - id: chat.script.command.close
+    path: scripts/00.chat/command/close/script.sh
+-->
+# Close Command
+
+`script.sh` is the canonical entrypoint for the public `chat:close` command. It
+delegates to `scripts/00.chat/closeout/build-closeout-prompt/script.sh`.
+
+The command exists so humans can use a stable public shortcut without knowing
+where closeout prompt construction lives internally.
+
+This command does not commit, merge, or push. It prepares the governed closeout
+prompt for a later agent turn.
+

package/scripts/00.chat/command/close/script.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# agentic-artifact:
+#   schema: agentic-artifact/v2
+#   id: chat.script.command.close
+#   version: 1
+#   status: active
+#   layer: 00.chat
+#   domain: command
+#   disciplines:
+#   - agentic
+#   kind: script
+#   purpose: Dispatch the public chat close command to the closeout prompt capability.
+#   portability:
+#     class: required
+#     targets:
+#     - llm-workbench
+#   used_by:
+#   - id: chat.script.command.dispatcher
+#     path: scripts/00.chat/command/dispatcher/script.sh
+#   effects:
+#   - read-only
+
+exec bash scripts/00.chat/closeout/build-closeout-prompt/script.sh "$@"

package/scripts/00.chat/command/dispatcher/README.md

@@ -0,0 +1,46 @@
+<!-- agentic-artifact:
+  schema: agentic-artifact/v2
+  id: chat.script.command.dispatcher.readme
+  version: 1
+  status: active
+  layer: 00.chat
+  domain: command
+  disciplines:
+  - agentic
+  kind: capability-readme
+  purpose: Explain the chat command dispatcher capability and its script layout.
+  portability:
+    class: required
+    targets:
+    - llm-workbench
+  used_by:
+  - id: harness.architecture.adr.0017-organize-scripts-by-owner-domain-and-capability
+  - id: chat.script.command.dispatcher
+    path: scripts/00.chat/command/dispatcher/script.sh
+-->
+# Chat Command Dispatcher
+
+This capability owns the chat command dispatcher.
+
+The dispatcher is the small command-line router for chat commands. It accepts a
+command name such as `list`, `new`, or `close`, validates the name, finds the
+matching script under `scripts/00.chat/command/<name>/script.sh`, and transfers
+control to that command through Bash.
+
+The dispatcher is not the implementation of each chat action. The subcommand
+scripts remain separate so each command can evolve independently.
+
+## Files
+
+- `script.sh` is the canonical dispatcher entrypoint.
+- `<command>/script.sh` files are canonical command entrypoints.
+- `smoke-test.sh` validates the dispatcher and core chat subcommands in a
+  throwaway repository.
+
+The dispatcher invokes command scripts with `bash` instead of requiring
+executable mode, so archive extraction or Windows filesystems that strip mode
+bits do not break the public command surface.
+
+The old `scripts/shared/chat/commands/` compatibility wrappers have been
+retired. Public callers should use `package.json` `chat:*` scripts; governed
+callers should use canonical `scripts/00.chat/command/...` paths.

package/scripts/00.chat/command/dispatcher/script.sh

@@ -0,0 +1,91 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# agentic-artifact:
+#   schema: agentic-artifact/v2
+#   id: chat.script.command.dispatcher
+#   version: 1
+#   status: active
+#   layer: 00.chat
+#   domain: command
+#   disciplines:
+#   - agentic
+#   kind: script
+#   purpose: Dispatch chat subcommands from canonical scripts/00.chat/command folders.
+#   portability:
+#     class: required
+#     targets:
+#     - llm-workbench
+#   used_by:
+#   - id: chat.commands.readme
+#     path: .agentic/00.chat/commands/README.md
+#   - id: chat.script.command.dispatcher.readme
+#     path: scripts/00.chat/command/dispatcher/README.md
+#   - id: chat.script.startup.auto-start-missing-session
+#     path: scripts/00.chat/startup/auto-start-missing-session/script.sh
+#   effects:
+#   - branches
+#   - stages-files
+#   - worktrees
+#   - writes-files
+
+COMMAND_DIR="scripts/00.chat/command"
+
+usage() {
+  cat <<EOF
+Usage: npm run chat -- <command> [args...]
+
+Commands:
+EOF
+
+  if [ -d "$COMMAND_DIR" ]; then
+    find "$COMMAND_DIR" -mindepth 2 -maxdepth 2 -type f -path '*/script.sh' \
+      ! -path "$COMMAND_DIR/dispatcher/script.sh" \
+      | sed -E 's#^scripts/00\.chat/command/([^/]+)/script\.sh$#  \1#' \
+      | sort
+  fi
+}
+
+if [ $# -eq 0 ]; then
+  usage
+  exit 0
+fi
+
+case "$1" in
+  -h|--help|help|list)
+    usage
+    exit 0
+    ;;
+esac
+
+COMMAND_NAME="$1"
+shift
+
+if [ "$COMMAND_NAME" = "open" ] && [ "${1:-}" = "window" ]; then
+  COMMAND_NAME="open-window"
+  shift
+fi
+
+case "$COMMAND_NAME" in
+  *[!a-zA-Z0-9_-]*|'')
+    echo "ERROR: invalid chat command name: $COMMAND_NAME" >&2
+    echo "Use letters, numbers, underscores, or hyphens." >&2
+    exit 2
+    ;;
+esac
+
+COMMAND_SCRIPT="${COMMAND_DIR}/${COMMAND_NAME}/script.sh"
+
+if [ "$COMMAND_NAME" = "dispatcher" ]; then
+  echo "ERROR: unknown chat command: $COMMAND_NAME" >&2
+  usage >&2
+  exit 2
+fi
+
+if [ ! -f "$COMMAND_SCRIPT" ]; then
+  echo "ERROR: unknown chat command: $COMMAND_NAME" >&2
+  usage >&2
+  exit 2
+fi
+
+exec bash "$COMMAND_SCRIPT" "$@"