llm-wb 0.1.0-beta.0

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

@@ -0,0 +1,294 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# agentic-artifact:
+#   schema: agentic-artifact/v2
+#   id: chat.script.session-log.update-chat-log
+#   version: 1
+#   status: active
+#   layer: 00.chat
+#   domain: session-log
+#   disciplines:
+#   - agentic
+#   kind: script
+#   purpose: Internal helper for appending structured entries to the current chat log.
+#   portability:
+#     class: internal
+#     targets: []
+#   used_by:
+#   - id: chat.checklists.before-commit
+#     path: .agentic/00.chat/checklists/before-commit.md
+#   effects:
+#   - writes-files
+
+# shellcheck source=../paths/lib.sh
+source "scripts/00.chat/session-log/paths/lib.sh"
+
+usage() {
+  cat <<'EOF'
+Usage:
+  update-chat-log.sh question <asked-summary> <response-summary>
+  update-chat-log.sh issue <issue-summary> <resolution-summary>
+  update-chat-log.sh decision <decision-summary> <rationale-summary>
+  update-chat-log.sh commit-summary <commit-or-message> <summary> [adr-impact]
+  update-chat-log.sh adr-disposition needed <adr-path> <reason>
+  update-chat-log.sh adr-disposition not-needed <reason>
+
+Updates the current chat branch session log under commitLogs/<yyyy>/<mmm>/<dd>/<session>/README.md.
+EOF
+}
+
+if [ $# -lt 1 ]; then
+  usage >&2
+  exit 2
+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
+
+TIMESTAMP="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+
+insert_section_entry() {
+  local section="$1"
+  local entry="$2"
+  local tmp
+  local entry_tmp
+
+  tmp="$(mktemp)"
+  entry_tmp="$(mktemp)"
+  printf '%s\n' "$entry" > "$entry_tmp"
+
+  if awk -v section="$section" -v entry_path="$entry_tmp" '
+    BEGIN {
+      in_section = 0
+      inserted = 0
+      found = 0
+      entry = ""
+      while ((getline line < entry_path) > 0) {
+        entry = entry (entry == "" ? "" : "\n") line
+      }
+      close(entry_path)
+    }
+    $0 == section {
+      found = 1
+      in_section = 1
+      print
+      next
+    }
+    in_section && /^## / && inserted == 0 {
+      print ""
+      print entry
+      print ""
+      inserted = 1
+      in_section = 0
+    }
+    in_section && $0 == "- None recorded yet." {
+      next
+    }
+    {
+      print
+    }
+    END {
+      if (found == 0) {
+        print ""
+        print section
+        print ""
+        print entry
+      } else if (in_section == 1 && inserted == 0) {
+        print ""
+        print entry
+      }
+    }
+  ' "$LOG_FILE" > "$tmp"; then
+    mv "$tmp" "$LOG_FILE"
+  else
+    rm -f "$tmp"
+    rm -f "$entry_tmp"
+    return 1
+  fi
+
+  rm -f "$entry_tmp"
+}
+
+set_adr_disposition() {
+  local needed="$1"
+  local path="$2"
+  local reason="$3"
+  local tmp
+
+  tmp="$(mktemp)"
+
+  awk -v needed="$needed" -v path="$path" -v reason="$reason" '
+    BEGIN {
+      in_adr = 0
+      saw_needed = 0
+      saw_path = 0
+      saw_reason = 0
+    }
+    $0 == "## ADR Disposition" {
+      in_adr = 1
+      print
+      next
+    }
+    in_adr && /^## / {
+      if (saw_needed == 0) {
+        print "ADR needed: " needed
+      }
+      if (saw_path == 0) {
+        print "ADR path: " path
+      }
+      if (saw_reason == 0) {
+        print "Reason: " reason
+      }
+      in_adr = 0
+    }
+    in_adr && /^ADR needed:/ {
+      print "ADR needed: " needed
+      saw_needed = 1
+      next
+    }
+    in_adr && /^ADR path:/ {
+      print "ADR path: " path
+      saw_path = 1
+      next
+    }
+    in_adr && /^Reason:/ {
+      print "Reason: " reason
+      saw_reason = 1
+      next
+    }
+    {
+      print
+    }
+    END {
+      if (in_adr == 1) {
+        if (saw_needed == 0) {
+          print "ADR needed: " needed
+        }
+        if (saw_path == 0) {
+          print "ADR path: " path
+        }
+        if (saw_reason == 0) {
+          print "Reason: " reason
+        }
+      }
+    }
+  ' "$LOG_FILE" > "$tmp"
+
+  mv "$tmp" "$LOG_FILE"
+}
+
+COMMAND="$1"
+shift
+
+case "$COMMAND" in
+  question)
+    if [ $# -ne 2 ]; then
+      usage >&2
+      exit 2
+    fi
+    insert_section_entry "## Questions Asked" "- Asked: $1
+  Response: $2"
+    insert_section_entry "## Activity Log" "### ${TIMESTAMP} - Question
+
+Asked: $1
+
+Response: $2"
+    ;;
+  issue)
+    if [ $# -ne 2 ]; then
+      usage >&2
+      exit 2
+    fi
+    insert_section_entry "## Issues Raised" "- Raised: $1
+  Resolution: $2"
+    insert_section_entry "## Activity Log" "### ${TIMESTAMP} - Issue
+
+Raised: $1
+
+Resolution: $2"
+    ;;
+  decision)
+    if [ $# -ne 2 ]; then
+      usage >&2
+      exit 2
+    fi
+    insert_section_entry "## Decisions Made" "- Decision: $1
+  Rationale: $2"
+    insert_section_entry "## Activity Log" "### ${TIMESTAMP} - Decision
+
+Decision: $1
+
+Rationale: $2"
+    ;;
+  commit-summary)
+    if [ $# -lt 2 ] || [ $# -gt 3 ]; then
+      usage >&2
+      exit 2
+    fi
+    ADR_IMPACT="${3:-covered by session ADR disposition}"
+    insert_section_entry "## Commits" "- Commit: $1
+  Summary: $2
+  ADR impact: ${ADR_IMPACT}"
+    insert_section_entry "## Activity Log" "### ${TIMESTAMP} - Commit summary
+
+Commit: $1
+
+Summary: $2
+
+ADR impact: ${ADR_IMPACT}"
+    ;;
+  adr-disposition)
+    if [ $# -lt 1 ]; then
+      usage >&2
+      exit 2
+    fi
+    case "$1" in
+      needed)
+        if [ $# -ne 3 ]; then
+          usage >&2
+          exit 2
+        fi
+        set_adr_disposition "yes" "$2" "$3"
+        insert_section_entry "## Activity Log" "### ${TIMESTAMP} - ADR disposition
+
+ADR needed: yes
+
+ADR path: $2
+
+Reason: $3"
+        ;;
+      not-needed)
+        if [ $# -ne 2 ]; then
+          usage >&2
+          exit 2
+        fi
+        set_adr_disposition "no" "" "$2"
+        insert_section_entry "## Activity Log" "### ${TIMESTAMP} - ADR disposition
+
+ADR needed: no
+
+Reason: $2"
+        ;;
+      *)
+        usage >&2
+        exit 2
+        ;;
+    esac
+    ;;
+  *)
+    usage >&2
+    exit 2
+    ;;
+esac

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

@@ -0,0 +1,37 @@
+<!-- agentic-artifact:
+  schema: agentic-artifact/v2
+  id: chat.script.startup.readme
+  version: 1
+  status: active
+  layer: 00.chat
+  domain: startup
+  disciplines:
+  - agentic
+  kind: script-domain-readme
+  purpose: Explain scripts that create or resume governed chat sessions.
+  portability:
+    class: required
+    targets:
+    - llm-workbench
+  used_by:
+  - id: chat.workflows.chat-start
+    path: .agentic/00.chat/workflows/chat-start.md
+  - id: chat.script.startup.start-chat-session.readme
+    path: scripts/00.chat/startup/start-chat-session/README.md
+-->
+# Startup Scripts
+
+Startup scripts create the governed working context for a chat. They handle
+task summaries, branch creation, chat-owned worktrees, session logs, latest
+context-packet continuity fields, and terminal handoff prompts.
+
+Startup is where the harness prevents the first turn from being ambiguous. A
+chat should begin with a known branch, known worktree, known chat lifecycle
+workflow, and known session log. Prompt-level layer, mode, workflow, corpus, and
+rule context is resolved later from the current request, repo assistant
+instructions, and any repo-provided context router if one exists.
+
+Agents following chat-start should use `resolve-current-chat-session` as the
+startup entrypoint. It reads existing chat metadata when available and
+auto-starts a missing session from the opening prompt when the repo is still on
+root `main` or otherwise lacks a matching chat log.

package/scripts/00.chat/startup/auto-start-missing-session/README.md

@@ -0,0 +1,113 @@
+<!-- agentic-artifact:
+  schema: agentic-artifact/v2
+  id: chat.script.startup.auto-start-missing-session.readme
+  version: 1
+  status: active
+  layer: 00.chat
+  domain: startup
+  disciplines:
+  - agentic
+  kind: capability-readme
+  purpose: Explain how opening-prompt auto-start decides whether to create a governed
+    chat session.
+  portability:
+    class: required
+    targets:
+    - llm-workbench
+  used_by:
+  - id: chat.script.startup.auto-start-missing-session
+    path: scripts/00.chat/startup/auto-start-missing-session/script.sh
+  - id: chat.script.command.dispatcher.smoke-test
+    path: scripts/00.chat/command/dispatcher/smoke-test.sh
+  - id: harness.architecture.adr.0017-organize-scripts-by-owner-domain-and-capability
+-->
+# Auto-Start Missing Session
+
+`script.sh` is the bridge between an opening user message and the normal chat
+startup engine.
+
+It exists for the moment when a chat starts without usable session metadata. In
+that case, the harness needs to decide whether the opening message should become
+a new governed chat session, or whether startup should stop and ask the human
+for clearer intent.
+
+## Mental Model
+
+Normal startup is explicit: a human or command asks to start a chat with a task
+summary.
+
+Auto-start is recovery startup: the harness has an opening prompt but no
+session log metadata yet. Rather than guessing silently, this script applies a
+small set of routing rules and then delegates to the normal `chat-command new`
+path.
+
+Agents should normally reach this through `resolve-current-chat-session`, which
+first checks whether current session metadata already exists and only delegates
+here for the missing-session path.
+
+That means auto-start does not create a separate startup model. It only turns a
+valid opening prompt into the same branch, worktree, session log, and first
+prompt that `start-chat-session` would create.
+
+## Decisions
+
+1. Empty prompt
+
+   An empty opening prompt is rejected. There is no task summary to name the
+   session, create a useful branch/worktree identity, or write useful session
+   metadata.
+
+2. Bare `new`
+
+   A message that is exactly `new` is treated as incomplete intent. The script
+   asks:
+
+   ```txt
+   What should the new chat be about?
+   ```
+
+   This prevents the harness from creating a low-information branch and log.
+
+3. `ignore chat start`
+
+   If the opening prompt begins with `ignore chat start`, auto-start exits
+   cleanly without creating a session. This is the explicit escape hatch for
+   chats that should bypass the chat-start workflow.
+
+4. Any other opening prompt
+
+   The prompt is passed to:
+
+   ```bash
+   bash scripts/00.chat/command/dispatcher/script.sh new "$PROMPT"
+   ```
+
+   The dispatcher then routes to the normal startup command.
+
+## What This Does Not Do
+
+- It does not classify tasks itself.
+- It does not create branches or worktrees directly.
+- It does not write the session log directly.
+- It does not bypass the normal startup engine.
+- It does not replace the governed runner allowlist for the old compatibility
+  path.
+
+## Validation
+
+The dispatcher smoke test covers this capability. It verifies that an opening
+prompt creates a chat session, that the task text is preserved, and that a bare
+`new` prompt asks for a task summary instead of creating a vague session.
+
+Run it with:
+
+```bash
+bash scripts/00.chat/command/dispatcher/smoke-test.sh
+```
+
+## Compatibility
+
+The old request-initialization entrypoint
+`scripts/shared/chat/request-initialization/auto-start-missing-session.sh` has
+been retired. New callers should use this canonical script through the governed
+runner.

package/scripts/00.chat/startup/auto-start-missing-session/script.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# agentic-artifact:
+#   schema: agentic-artifact/v2
+#   id: chat.script.startup.auto-start-missing-session
+#   version: 1
+#   status: active
+#   layer: 00.chat
+#   domain: startup
+#   disciplines:
+#   - agentic
+#   kind: script
+#   purpose: Convert an opening prompt into a governed chat session when metadata is missing.
+#   portability:
+#     class: required
+#     targets:
+#     - llm-workbench
+#   used_by:
+#   - id: chat.commands.readme
+#     path: .agentic/00.chat/commands/README.md
+#   - id: chat.script.startup.auto-start-missing-session.readme
+#     path: scripts/00.chat/startup/auto-start-missing-session/README.md
+#   effects:
+#   - branches
+#   - worktrees
+#   - writes-files
+#   - stages-files
+OPENING_PROMPT="${*:-}"
+
+trimmed_prompt() {
+  printf '%s' "$OPENING_PROMPT" | sed -E 's/^[[:space:]]+//; s/[[:space:]]+$//'
+}
+
+PROMPT="$(trimmed_prompt)"
+PROMPT_LOWER="$(printf '%s' "$PROMPT" | tr '[:upper:]' '[:lower:]')"
+
+if [ -z "${PROMPT// }" ]; then
+  echo "ERROR: opening prompt is required." >&2
+  exit 2
+fi
+
+case "$PROMPT_LOWER" in
+  "new")
+    echo "What should the new chat be about?"
+    exit 2
+    ;;
+  ignore\ chat\ start*)
+    echo "Skipping chat auto-start because the opening prompt begins with 'ignore chat start'."
+    exit 0
+    ;;
+esac
+
+exec bash scripts/00.chat/command/dispatcher/script.sh new "$PROMPT"

package/scripts/00.chat/startup/resolve-current-chat-session/README.md

@@ -0,0 +1,57 @@
+<!-- agentic-artifact:
+  schema: agentic-artifact/v2
+  id: chat.script.startup.resolve-current-chat-session.readme
+  version: 1
+  status: active
+  layer: 00.chat
+  domain: startup
+  disciplines:
+  - agentic
+  kind: capability-readme
+  purpose: Explain the startup resolver that reads current metadata or auto-starts
+    missing chat sessions.
+  portability:
+    class: required
+    targets:
+    - llm-workbench
+  used_by:
+  - id: chat.script.startup.resolve-current-chat-session
+    path: scripts/00.chat/startup/resolve-current-chat-session/script.sh
+  - id: chat.workflows.chat-start
+    path: .agentic/00.chat/workflows/chat-start.md
+-->
+# Resolve Current Chat Session
+
+`script.sh` is the single startup entrypoint for agents following the chat-start
+workflow.
+
+It first asks `read-current-chat-log` for existing session metadata. If the
+current branch is already a usable chat branch, the metadata is printed and no
+startup mutation happens.
+
+If the current branch has no matching chat session, including the common root
+`main` case, the script delegates to `auto-start-missing-session` with the
+opening user message. That creates the normal chat branch, chat-owned worktree,
+session log, and first prompt.
+
+Other failures are passed through unchanged. In particular,
+`recorded-session-approval-required` remains a stop condition until the user
+explicitly approves continuing the recorded chat/worktree.
+
+Run it through the governed runner:
+
+```bash
+bash scripts/01.harness/run-governed-script.sh --approved-action scripts/00.chat/startup/resolve-current-chat-session/script.sh "<opening user message>"
+```
+
+## Validation
+
+Run the smoke test with:
+
+```bash
+bash scripts/00.chat/startup/resolve-current-chat-session/smoke-test.sh
+```
+
+It verifies that root `main` with no chat session auto-starts from the opening
+prompt, and that an existing chat worktree returns metadata without creating a
+second chat branch.

package/scripts/00.chat/startup/resolve-current-chat-session/script.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# agentic-artifact:
+#   schema: agentic-artifact/v2
+#   id: chat.script.startup.resolve-current-chat-session
+#   version: 1
+#   status: active
+#   layer: 00.chat
+#   domain: startup
+#   disciplines:
+#   - agentic
+#   kind: script
+#   purpose: Resolve startup to current chat metadata or auto-start a missing session.
+#   portability:
+#     class: required
+#     targets:
+#     - llm-workbench
+#   used_by:
+#   - id: chat.workflows.chat-start
+#     path: .agentic/00.chat/workflows/chat-start.md
+#   effects:
+#   - branches
+#   - worktrees
+#   - writes-files
+#   - stages-files
+
+OPENING_PROMPT="${*:-}"
+
+set +e
+CURRENT_METADATA="$(bash scripts/00.chat/session-log/read-current-chat-log/script.sh 2>&1)"
+READ_STATUS=$?
+set -e
+
+if [ "$READ_STATUS" -eq 0 ]; then
+  printf '%s\n' "$CURRENT_METADATA"
+  exit 0
+fi
+
+case "$CURRENT_METADATA" in
+  *"ERROR: current branch is not a chat branch:"*|*"ERROR: missing chat log:"*)
+    exec bash scripts/00.chat/startup/auto-start-missing-session/script.sh "$OPENING_PROMPT"
+    ;;
+esac
+
+printf '%s\n' "$CURRENT_METADATA"
+exit "$READ_STATUS"