llm-wb 0.1.0-beta.0

package/scripts/01.harness/run-governed-script.sh

@@ -0,0 +1,178 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# agentic-artifact:
+#   schema: agentic-artifact/v2
+#   id: harness.script.run-governed-script
+#   version: 1
+#   status: active
+#   layer: 01.harness
+#   domain: governance
+#   disciplines:
+#   - agentic
+#   kind: script
+#   purpose: Run only explicitly governed repository scripts with approval-sensitive routing.
+#   portability:
+#     class: required
+#     targets:
+#     - llm-workbench
+#   used_by:
+#   - id: harness.standards.governed-script-permissions
+#   - id: chat.workflows.chat-start
+#     path: .agentic/00.chat/workflows/chat-start.md
+#   effects:
+#   - read-only
+
+usage() {
+  cat <<'EOF'
+Usage:
+  run-governed-script.sh [--approved-action] <script> [args...]
+  run-governed-script.sh --list
+
+Runs only explicitly governed repository scripts.
+
+Use --approved-action only after the current chat has explicit approval for the
+action class governed by the active workflow.
+EOF
+}
+
+has_artifact_header() {
+  sed -n '1,80p' "$1" | grep -Fq "agentic-artifact:"
+}
+
+metadata_has_line() {
+  local path="$1"
+  local value="$2"
+
+  sed -n '1,140p' "$path" | grep -Eq "^[#[:space:]]*-[[:space:]]*$value[[:space:]]*$"
+}
+
+has_never_persistent_effect() {
+  local path="$1"
+
+  case "$path" in
+    scripts/00.chat/main-refresh/apply-rehearsed-refresh/script.sh)
+      return 1
+      ;;
+  esac
+
+  metadata_has_line "$path" "destructive" ||
+    metadata_has_line "$path" "push" ||
+    metadata_has_line "$path" "history-rewrite" ||
+    metadata_has_line "$path" "overwrites" ||
+    metadata_has_line "$path" "cloud" ||
+    metadata_has_line "$path" "database"
+}
+
+classify_script() {
+  local path="$1"
+
+  case "$path" in
+    */lib.sh)
+      echo "ERROR: governed library files must not be invoked directly: $path" >&2
+      return 1
+      ;;
+  esac
+
+  case "$path" in
+    scripts/[0-9][0-9].*/*.sh|scripts/[0-9][0-9].*/*/script.sh|scripts/[0-9][0-9].*/*/smoke-test.sh|\
+    scripts/[0-9][0-9].*/*/*/script.sh|scripts/[0-9][0-9].*/*/*/smoke-test.sh)
+      ;;
+    scripts/shared/*.sh|scripts/shared/*/*.sh)
+      echo "ERROR: retired shared script path must not be invoked directly: $path" >&2
+      return 1
+      ;;
+    *)
+      echo "ERROR: refused script outside canonical governed script paths: $path" >&2
+      return 1
+      ;;
+  esac
+
+  if [ ! -f "$path" ]; then
+    echo "ERROR: governed script does not exist: $path" >&2
+    return 1
+  fi
+
+  if ! has_artifact_header "$path"; then
+    echo "ERROR: script is missing governed agentic-artifact metadata: $path" >&2
+    return 1
+  fi
+
+  if has_never_persistent_effect "$path"; then
+    echo "ERROR: script has effects that are never persistent-auto-approved: $path" >&2
+    return 1
+  fi
+
+  if metadata_has_line "$path" "read-only" &&
+    ! metadata_has_line "$path" "writes-files" &&
+    ! metadata_has_line "$path" "commits" &&
+    ! metadata_has_line "$path" "network"; then
+    printf '%s\n' "always"
+    return 0
+  fi
+
+  printf '%s\n' "approved"
+}
+
+APPROVED_ACTION="no"
+
+if [ $# -eq 0 ]; then
+  usage >&2
+  exit 2
+fi
+
+case "$1" in
+  --approved-action)
+    APPROVED_ACTION="yes"
+    shift
+    ;;
+  --list)
+    REPO_ROOT="$(git rev-parse --show-toplevel)"
+    cd "$REPO_ROOT"
+    git ls-files 'scripts/*.sh' 'scripts/*/*.sh' 'scripts/*/*/*.sh' 'scripts/*/*/*/*.sh' |
+      while IFS= read -r script_path; do
+        run_class="$(classify_script "$script_path" 2>/dev/null || true)"
+        if [ -n "$run_class" ]; then
+          printf '%s %s\n' "$run_class" "$script_path"
+        fi
+      done
+    exit 0
+    ;;
+  -h|--help)
+    usage
+    exit 0
+    ;;
+esac
+
+if [ $# -eq 0 ]; then
+  usage >&2
+  exit 2
+fi
+
+SCRIPT_PATH="$1"
+shift
+
+case "$SCRIPT_PATH" in
+  /*|*../*|../*|*"/.."|*".."|*"
+"*)
+    echo "ERROR: refused non-repository script path: $SCRIPT_PATH" >&2
+    exit 1
+    ;;
+esac
+
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+cd "$REPO_ROOT"
+
+RUN_CLASS="$(classify_script "$SCRIPT_PATH")"
+
+if [ "$RUN_CLASS" = "approved" ] && [ "$APPROVED_ACTION" != "yes" ]; then
+  echo "ERROR: approval-sensitive script requires --approved-action: $SCRIPT_PATH" >&2
+  exit 1
+fi
+
+if [ ! -f "$SCRIPT_PATH" ]; then
+  echo "ERROR: governed script does not exist: $SCRIPT_PATH" >&2
+  exit 1
+fi
+
+exec bash "$SCRIPT_PATH" "$@"

package/scripts/install.sh

@@ -0,0 +1,503 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# agentic-artifact:
+#   schema: agentic-artifact/v2
+#   id: chat.script.install
+#   version: 1
+#   status: active
+#   layer: 00.chat
+#   domain: install
+#   disciplines:
+#   - agentic
+#   kind: script
+#   purpose: Install the llm-workbench chat harness into a target Git repository.
+#   portability:
+#     class: required
+#     targets:
+#     - llm-workbench
+#   used_by:
+#   - id: llm-workbench.docs.install
+#   effects:
+#   - writes-files
+#   - commits
+
+usage() {
+  cat <<'EOF'
+Usage:
+  scripts/install.sh [--dry-run|--apply] [--init-commit] <target-git-repo>
+
+Installs the llm-workbench chat harness into a target Git repository.
+
+The installer always plans first. Apply mode refuses to write when the plan has
+conflicts. Existing package.json files are merged by adding only workbench-owned
+chat:* scripts. Existing assistant instruction files are patched with a managed
+llm-workbench block instead of being overwritten.
+EOF
+}
+
+MODE=""
+INIT_COMMIT="no"
+TARGET_REPO=""
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --dry-run)
+      [ -z "$MODE" ] || { echo "ERROR: choose one mode." >&2; exit 2; }
+      MODE="dry-run"
+      shift
+      ;;
+    --apply)
+      [ -z "$MODE" ] || { echo "ERROR: choose one mode." >&2; exit 2; }
+      MODE="apply"
+      shift
+      ;;
+    --init-commit)
+      INIT_COMMIT="yes"
+      shift
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    -*)
+      echo "ERROR: unknown argument: $1" >&2
+      usage >&2
+      exit 2
+      ;;
+    *)
+      [ -z "$TARGET_REPO" ] || { echo "ERROR: target repo specified twice." >&2; exit 2; }
+      TARGET_REPO="$1"
+      shift
+      ;;
+  esac
+done
+
+MODE="${MODE:-apply}"
+
+if [ -z "$TARGET_REPO" ]; then
+  usage >&2
+  exit 2
+fi
+
+if [ ! -d "$TARGET_REPO/.git" ]; then
+  echo "ERROR: target is not a Git repo: $TARGET_REPO" >&2
+  exit 1
+fi
+
+if [ "$INIT_COMMIT" = "yes" ] && [ "$MODE" = "apply" ]; then
+  if git -C "$TARGET_REPO" rev-parse --verify HEAD >/dev/null 2>&1; then
+    echo "ERROR: --init-commit is only for repos with no existing HEAD." >&2
+    exit 2
+  fi
+fi
+
+SOURCE_REPO="$(cd "$(dirname "$0")/.." && pwd)"
+TMP_DIR="$(mktemp -d "${TMPDIR:-/tmp}/llm-workbench-install-plan.XXXXXX")"
+PLAN_PATHS="$TMP_DIR/planned-paths.txt"
+FILE_ACTIONS="$TMP_DIR/file-actions.tsv"
+PACKAGE_OUTPUT="$TMP_DIR/package-output.txt"
+MANIFEST_OUTPUT="$TMP_DIR/install-manifest.tsv"
+MANIFEST_PATH="$TARGET_REPO/.llm-workbench/install-manifest.tsv"
+
+cleanup() {
+  rm -rf "$TMP_DIR"
+}
+trap cleanup EXIT
+
+: > "$PLAN_PATHS"
+: > "$FILE_ACTIONS"
+: > "$MANIFEST_OUTPUT"
+
+CREATE_COUNT=0
+SAME_COUNT=0
+PATCH_COUNT=0
+CONFLICT_COUNT=0
+PACKAGE_CONFLICTS="no"
+
+managed_block() {
+  cat <<'EOF'
+
+<!-- llm-workbench:start -->
+## llm-workbench
+
+Follow `.agentic/00.chat/workflows/chat-start.md` at the start of each chat.
+Use `commitLogs/<session>/README.md` as the first source of truth for chat
+lifecycle, branch, worktree, context-packet references, commits, and metrics.
+
+Do not assign the whole chat a durable layer, mode, or workflow. When a prompt
+needs layer, mode, workflow, corpus, or rule context, use the current user
+request, this repo's assistant instructions, and any repo-provided context
+router if one exists.
+
+Default mode after governed chat-start bootstrap is read-only until the user
+explicitly grants write permission for task files.
+<!-- llm-workbench:end -->
+EOF
+}
+
+record_path() {
+  printf '%s\n' "$1" >> "$PLAN_PATHS"
+}
+
+plan_file() {
+  local source="$1"
+  local relative_path="$2"
+  local target="$TARGET_REPO/$relative_path"
+
+  record_path "$relative_path"
+
+  if [ -e "$target" ]; then
+    if cmp -s "$source" "$target"; then
+      echo "SAME $relative_path"
+      printf 'SAME\t%s\t%s\n' "$source" "$relative_path" >> "$FILE_ACTIONS"
+      SAME_COUNT=$((SAME_COUNT + 1))
+    else
+      echo "CONFLICT $relative_path"
+      printf 'CONFLICT\t%s\t%s\n' "$source" "$relative_path" >> "$FILE_ACTIONS"
+      CONFLICT_COUNT=$((CONFLICT_COUNT + 1))
+    fi
+  else
+    echo "CREATE $relative_path"
+    printf 'CREATE\t%s\t%s\n' "$source" "$relative_path" >> "$FILE_ACTIONS"
+    CREATE_COUNT=$((CREATE_COUNT + 1))
+  fi
+}
+
+plan_instruction_file() {
+  local source="$1"
+  local relative_path="$2"
+  local target="$TARGET_REPO/$relative_path"
+
+  [ -f "$source" ] || return 0
+  record_path "$relative_path"
+
+  if [ ! -e "$target" ]; then
+    echo "CREATE $relative_path"
+    printf 'CREATE\t%s\t%s\n' "$source" "$relative_path" >> "$FILE_ACTIONS"
+    CREATE_COUNT=$((CREATE_COUNT + 1))
+    return 0
+  fi
+
+  if cmp -s "$source" "$target"; then
+    echo "SAME $relative_path"
+    printf 'SAME\t%s\t%s\n' "$source" "$relative_path" >> "$FILE_ACTIONS"
+    SAME_COUNT=$((SAME_COUNT + 1))
+    return 0
+  fi
+
+  if grep -q 'llm-workbench:start' "$target"; then
+    echo "SAME_BLOCK $relative_path"
+    printf 'SAME_BLOCK\t%s\t%s\n' "$source" "$relative_path" >> "$FILE_ACTIONS"
+    SAME_COUNT=$((SAME_COUNT + 1))
+  else
+    echo "PATCH_BLOCK $relative_path"
+    printf 'PATCH_BLOCK\t%s\t%s\n' "$source" "$relative_path" >> "$FILE_ACTIONS"
+    PATCH_COUNT=$((PATCH_COUNT + 1))
+  fi
+}
+
+plan_tree() {
+  local tree="$1"
+  local file
+  local relative_path
+
+  [ -d "$SOURCE_REPO/$tree" ] || return 0
+
+  while IFS= read -r file; do
+    relative_path="${file#$SOURCE_REPO/}"
+    case "$relative_path" in
+      scripts/00.chat/upstream/*)
+        continue
+        ;;
+    esac
+    plan_file "$file" "$relative_path"
+  done < <(find "$SOURCE_REPO/$tree" -type f | sort)
+}
+
+plan_selected_file() {
+  local path="$1"
+
+  [ -f "$SOURCE_REPO/$path" ] || return 0
+  plan_file "$SOURCE_REPO/$path" "$path"
+}
+
+plan_public_harness_scripts() {
+  plan_selected_file "scripts/01.harness/run-governed-script.sh"
+  plan_selected_file "scripts/01.harness/check-deterministic-process-drift.sh"
+  plan_selected_file "scripts/01.harness/check-governed-script-command-drift.sh"
+  plan_selected_file "scripts/01.harness/artifact-metadata/check-headers/script.sh"
+  plan_selected_file "scripts/01.harness/artifact-metadata/check-headers/smoke-test.sh"
+}
+
+plan_package_json() {
+  local target_package="$TARGET_REPO/package.json"
+  local template_package="$SOURCE_REPO/package.json"
+
+  record_path "package.json"
+
+  if [ ! -f "$target_package" ]; then
+    echo "CREATE package.json"
+    printf 'CREATE_PACKAGE\t%s\tpackage.json\n' "$template_package" >> "$FILE_ACTIONS"
+    CREATE_COUNT=$((CREATE_COUNT + 1))
+    return 0
+  fi
+
+  printf 'MERGE_PACKAGE\t%s\tpackage.json\n' "$template_package" >> "$FILE_ACTIONS"
+
+  if ! node - "$target_package" "$template_package" > "$PACKAGE_OUTPUT" <<'NODE'
+const fs = require('fs');
+const targetPath = process.argv[2];
+const templatePath = process.argv[3];
+
+let target;
+let template;
+
+try {
+  target = JSON.parse(fs.readFileSync(targetPath, 'utf8'));
+} catch (error) {
+  console.log(`CONFLICT package.json invalid-json ${error.message}`);
+  process.exit(1);
+}
+
+try {
+  template = JSON.parse(fs.readFileSync(templatePath, 'utf8'));
+} catch (error) {
+  console.log(`CONFLICT package.json template-invalid-json ${error.message}`);
+  process.exit(1);
+}
+
+const actualScripts = target.scripts || {};
+const expectedScripts = template.scripts || {};
+let conflicts = 0;
+
+for (const [name, expected] of Object.entries(expectedScripts)) {
+  const actual = actualScripts[name];
+  if (!name.startsWith('chat:') && name !== 'chat') {
+    continue;
+  }
+  if (actual === undefined) {
+    console.log(`PACKAGE_ADD_SCRIPT ${name} ${expected}`);
+  } else if (actual === expected) {
+    console.log(`PACKAGE_SAME_SCRIPT ${name}`);
+  } else {
+    console.log(`PACKAGE_CONFLICT_SCRIPT ${name} actual=${actual} expected=${expected}`);
+    conflicts += 1;
+  }
+}
+
+for (const name of Object.keys(actualScripts).sort()) {
+  if (expectedScripts[name] === undefined || (!name.startsWith('chat:') && name !== 'chat')) {
+    console.log(`PACKAGE_PRESERVE_SCRIPT ${name} ${actualScripts[name]}`);
+  }
+}
+
+process.exit(conflicts > 0 ? 1 : 0);
+NODE
+  then
+    PACKAGE_CONFLICTS="yes"
+    CONFLICT_COUNT=$((CONFLICT_COUNT + 1))
+  fi
+
+  cat "$PACKAGE_OUTPUT"
+}
+
+print_header() {
+  local head
+  local branch
+
+  head="$(git -C "$TARGET_REPO" rev-parse --verify HEAD 2>/dev/null || true)"
+  branch="$(git -C "$TARGET_REPO" branch --show-current 2>/dev/null || true)"
+
+  echo "llm-workbench install ${MODE}"
+  echo
+  echo "Source repo: $SOURCE_REPO"
+  echo "Target repo: $TARGET_REPO"
+  echo "Target branch: ${branch:-<none>}"
+  echo "Target HEAD: ${head:-<unborn>}"
+  echo "Target OS: ${LLM_WORKBENCH_TARGET_OS:-auto}"
+  echo
+}
+
+print_header
+
+echo "Package plan:"
+plan_package_json
+echo
+
+echo "File plan:"
+plan_instruction_file "$SOURCE_REPO/AGENTS.md" "AGENTS.md"
+plan_instruction_file "$SOURCE_REPO/CLAUDE.md" "CLAUDE.md"
+plan_instruction_file "$SOURCE_REPO/.github/copilot-instructions.md" ".github/copilot-instructions.md"
+plan_instruction_file "$SOURCE_REPO/.cursor/rules/llm-workbench.mdc" ".cursor/rules/llm-workbench.mdc"
+plan_instruction_file "$SOURCE_REPO/LLM_WORKBENCH.md" "LLM_WORKBENCH.md"
+plan_tree "bin"
+plan_tree ".agentic/00.chat"
+plan_tree ".agentic/shared"
+plan_tree "scripts/00.chat"
+plan_public_harness_scripts
+echo
+
+echo "Excluded source paths:"
+echo "EXCLUDE commitLogs/"
+echo "EXCLUDE .agentic/01.harness/"
+echo "EXCLUDE scripts/00.chat/upstream/"
+echo "EXCLUDE docs/"
+echo "EXCLUDE public repo templates, local transcripts, and local worktree paths"
+echo
+
+echo "Summary:"
+echo "create: $CREATE_COUNT"
+echo "same: $SAME_COUNT"
+echo "patch: $PATCH_COUNT"
+echo "conflicts: $CONFLICT_COUNT"
+echo "package_conflicts: $PACKAGE_CONFLICTS"
+echo "mode: $MODE"
+
+if [ "$CONFLICT_COUNT" -gt 0 ]; then
+  exit 1
+fi
+
+copy_file() {
+  local source="$1"
+  local relative_path="$2"
+  local target="$TARGET_REPO/$relative_path"
+
+  mkdir -p "$(dirname "$target")"
+  cp "$source" "$target"
+}
+
+record_manifest() {
+  local kind="$1"
+  local value="$2"
+
+  printf '%s\t%s\n' "$kind" "$value" >> "$MANIFEST_OUTPUT"
+}
+
+patch_instruction_file() {
+  local relative_path="$1"
+  local target="$TARGET_REPO/$relative_path"
+
+  managed_block >> "$target"
+}
+
+merge_package_json() {
+  local target_package="$TARGET_REPO/package.json"
+  local template_package="$SOURCE_REPO/package.json"
+
+  node - "$target_package" "$template_package" <<'NODE'
+const fs = require('fs');
+const targetPath = process.argv[2];
+const templatePath = process.argv[3];
+
+const target = JSON.parse(fs.readFileSync(targetPath, 'utf8'));
+const template = JSON.parse(fs.readFileSync(templatePath, 'utf8'));
+
+target.scripts = target.scripts || {};
+for (const [name, expected] of Object.entries(template.scripts || {})) {
+  if (!name.startsWith('chat:') && name !== 'chat') {
+    continue;
+  }
+  if (target.scripts[name] === undefined || target.scripts[name] === expected) {
+    target.scripts[name] = expected;
+  } else {
+    throw new Error(`conflicting script during apply: ${name}`);
+  }
+}
+
+fs.writeFileSync(targetPath, `${JSON.stringify(target, null, 2)}\n`);
+NODE
+}
+
+record_added_package_scripts() {
+  sed -n 's/^PACKAGE_ADD_SCRIPT \([^ ]*\) .*/\1/p' "$PACKAGE_OUTPUT" \
+    | while IFS= read -r script_name; do
+        [ -n "$script_name" ] || continue
+        record_manifest "package-script" "$script_name"
+      done
+}
+
+apply_plan() {
+  local action
+  local source
+  local relative_path
+
+  echo
+  echo "Applying clean plan..."
+
+  while IFS=$'\t' read -r action source relative_path; do
+    case "$action" in
+      CREATE)
+        copy_file "$source" "$relative_path"
+        record_manifest "create" "$relative_path"
+        echo "APPLIED_CREATE $relative_path"
+        ;;
+      CREATE_PACKAGE)
+        copy_file "$source" "$relative_path"
+        record_manifest "create" "$relative_path"
+        echo "APPLIED_CREATE package.json"
+        ;;
+      MERGE_PACKAGE)
+        merge_package_json
+        record_added_package_scripts
+        echo "APPLIED_MERGE package.json"
+        ;;
+      PATCH_BLOCK)
+        patch_instruction_file "$relative_path"
+        record_manifest "patch-block" "$relative_path"
+        echo "APPLIED_PATCH_BLOCK $relative_path"
+        ;;
+      SAME|SAME_BLOCK)
+        :
+        ;;
+      *)
+        echo "ERROR: unexpected action in clean plan: $action" >&2
+        exit 1
+        ;;
+    esac
+  done < "$FILE_ACTIONS"
+
+  echo "Apply completed."
+
+  mkdir -p "$(dirname "$MANIFEST_PATH")"
+  cp "$MANIFEST_OUTPUT" "$MANIFEST_PATH"
+  echo "Wrote install manifest: ${MANIFEST_PATH#$TARGET_REPO/}"
+}
+
+if [ "$MODE" = "apply" ]; then
+  apply_plan
+fi
+
+stage_install_paths() {
+  local kind
+  local value
+  local staged_package_json="no"
+
+  while IFS=$'\t' read -r kind value; do
+    case "$kind" in
+      create|patch-block)
+        git -C "$TARGET_REPO" add -- "$value"
+        ;;
+      package-script)
+        if [ "$staged_package_json" = "no" ]; then
+          git -C "$TARGET_REPO" add -- package.json
+          staged_package_json="yes"
+        fi
+        ;;
+    esac
+  done < "$MANIFEST_OUTPUT"
+
+  git -C "$TARGET_REPO" add -- .llm-workbench/install-manifest.tsv
+}
+
+if [ "$INIT_COMMIT" = "yes" ] && [ "$MODE" = "apply" ]; then
+  echo
+  echo "Creating install commit..."
+  stage_install_paths
+  if ! git -C "$TARGET_REPO" diff --cached --quiet; then
+    git -C "$TARGET_REPO" commit -m "Install llm-workbench harness"
+    echo "Install commit created."
+  else
+    echo "No install changes to commit."
+  fi
+fi