llm-wb 0.1.0-beta.0

package/scripts/00.chat/session-log/check-commit-prerequisites/script.sh

@@ -0,0 +1,121 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# agentic-artifact:
+#   schema: agentic-artifact/v2
+#   id: chat.script.session-log.check-commit-prerequisites
+#   version: 1
+#   status: active
+#   layer: 00.chat
+#   domain: session-log
+#   disciplines:
+#   - agentic
+#   kind: script
+#   purpose: Verify commit-boundary workflow, checklist, and referenced gate files exist.
+#   portability:
+#     class: required
+#     targets:
+#     - llm-workbench
+#   used_by:
+#   - id: chat.script.session-log.check-commit-prerequisites.readme
+#     path: scripts/00.chat/session-log/check-commit-prerequisites/README.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"
+
+BRANCH="$(git branch --show-current)"
+CHECKLIST=".agentic/00.chat/checklists/before-commit.md"
+
+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")"
+FAILURES=0
+
+fail() {
+  echo "ERROR: $*" >&2
+  FAILURES=$((FAILURES + 1))
+}
+
+ok() {
+  echo "OK: $*"
+}
+
+metadata_value() {
+  local key="$1"
+  sed -n "/<!-- agentic-session/,/-->/s/^${key}: //p" "$LOG_FILE" | head -n 1
+}
+
+check_file() {
+  local path="$1"
+  local description="$2"
+
+  if [ -f "$path" ]; then
+    ok "$description exists: $path"
+  else
+    fail "$description is missing: $path"
+  fi
+}
+
+collect_script_refs() {
+  local file="$1"
+
+  if [ ! -f "$file" ]; then
+    return
+  fi
+
+  grep -Eo "scripts/[^ \`\"']+\.sh" "$file" || true
+}
+
+if [ ! -f "$LOG_FILE" ]; then
+  fail "missing chat log: $LOG_FILE"
+else
+  ok "chat log exists: $LOG_FILE"
+fi
+
+WORKFLOW=""
+if [ -f "$LOG_FILE" ]; then
+  WORKFLOW="$(metadata_value "chat_lifecycle_workflow")"
+  if [ -z "${WORKFLOW// }" ]; then
+    WORKFLOW="$(metadata_value "workflow")"
+  fi
+fi
+
+if [ -z "${WORKFLOW// }" ]; then
+  fail "session metadata is missing chat_lifecycle_workflow"
+else
+  check_file "$WORKFLOW" "declared chat lifecycle workflow"
+fi
+
+check_file "$CHECKLIST" "canonical before-commit checklist"
+
+SCRIPT_REFS=""
+if [ -n "${WORKFLOW// }" ] && [ -f "$WORKFLOW" ]; then
+  SCRIPT_REFS="$SCRIPT_REFS
+$(collect_script_refs "$WORKFLOW")"
+fi
+
+if [ -f "$CHECKLIST" ]; then
+  SCRIPT_REFS="$SCRIPT_REFS
+$(collect_script_refs "$CHECKLIST")"
+fi
+
+while IFS= read -r script_path; do
+  if [ -z "${script_path// }" ]; then
+    continue
+  fi
+  check_file "$script_path" "referenced gate script"
+done < <(printf '%s\n' "$SCRIPT_REFS" | sort -u)
+
+if [ "$FAILURES" -gt 0 ]; then
+  echo "Commit prerequisites are missing. Repair branch state before committing." >&2
+  exit 1
+fi
+
+echo "Commit prerequisites are present."

package/scripts/00.chat/session-log/check-commit-prerequisites/smoke-test.sh

@@ -0,0 +1,119 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# agentic-artifact:
+#   schema: agentic-artifact/v2
+#   id: chat.script.session-log.check-commit-prerequisites.smoke-test
+#   version: 1
+#   status: active
+#   layer: 00.chat
+#   domain: session-log
+#   disciplines:
+#   - agentic
+#   kind: script
+#   purpose: Smoke test commit prerequisite validation and missing-file failures.
+#   portability:
+#     class: reusable
+#     targets:
+#     - llm-workbench
+#   used_by:
+#   - id: chat.script.session-log.check-commit-prerequisites.readme
+#     path: scripts/00.chat/session-log/check-commit-prerequisites/README.md
+#   - id: chat.script.session-log.check-commit-prerequisites
+#     path: scripts/00.chat/session-log/check-commit-prerequisites/script.sh
+#   effects:
+#   - writes-files
+#   - branches
+#   - commits
+fail() {
+  echo "FAIL: $*" >&2
+  exit 1
+}
+
+SOURCE_ROOT="$(git rev-parse --show-toplevel)"
+TMP_ROOT="$(mktemp -d "${TMPDIR:-/tmp}/commit-prerequisites-smoke.XXXXXX")"
+
+cleanup() {
+  rm -rf "$TMP_ROOT"
+}
+
+trap cleanup EXIT
+
+REPO="$TMP_ROOT/repo"
+mkdir -p "$REPO"
+git -C "$REPO" init --quiet --initial-branch=main
+
+mkdir -p \
+  "$REPO/.agentic/00.chat/checklists" \
+  "$REPO/.agentic/00.chat/workflows" \
+  "$REPO/commitLogs/2026/jun/19/2026-06-19-13-11-test" \
+  "$REPO/scripts/00.chat/session-log/check-commit-prerequisites" \
+  "$REPO/scripts/00.chat/session-log/read-current-chat-log" \
+  "$REPO/scripts/00.chat/session-log/paths" \
+  "$REPO/scripts/01.harness"
+
+cp "$SOURCE_ROOT/scripts/00.chat/session-log/paths/lib.sh" "$REPO/scripts/00.chat/session-log/paths/lib.sh"
+cp "$SOURCE_ROOT/scripts/00.chat/session-log/check-commit-prerequisites/script.sh" "$REPO/scripts/00.chat/session-log/check-commit-prerequisites/script.sh"
+chmod +x "$REPO/scripts/00.chat/session-log/check-commit-prerequisites/script.sh"
+
+cat > "$REPO/.agentic/00.chat/checklists/before-commit.md" <<'EOF'
+# Before Commit
+
+Run:
+
+```bash
+bash scripts/00.chat/session-log/check-commit-prerequisites/script.sh
+```
+EOF
+
+cat > "$REPO/.agentic/00.chat/workflows/chat-start.md" <<'EOF'
+# Chat Start
+
+Run:
+
+```bash
+bash scripts/00.chat/session-log/read-current-chat-log/script.sh
+```
+
+The executable startup scripts live under canonical `scripts/00.chat/`
+capability folders.
+EOF
+
+printf '#!/usr/bin/env bash\n' > "$REPO/scripts/00.chat/session-log/read-current-chat-log/script.sh"
+
+cat > "$REPO/commitLogs/2026/jun/19/2026-06-19-13-11-test/README.md" <<'EOF'
+# Chat Session: test
+
+<!-- agentic-session
+id: 2026-06-19-13-11-test
+task: test
+branch: chat/2026-06-19-13-11-test
+worktree:
+chat_lifecycle_workflow: .agentic/00.chat/workflows/chat-start.md
+latest_context_packet_id:
+latest_context_packet_routing_summary:
+latest_context_packet_at_utc:
+status: ready
+-->
+EOF
+
+git -C "$REPO" add .
+git -C "$REPO" -c user.name='Smoke Test' -c user.email='smoke@example.invalid' commit --quiet -m 'base'
+git -C "$REPO" switch --quiet -c chat/2026-06-19-13-11-test
+
+if sed -n '/<!-- agentic-session/,/-->/p' "$REPO/commitLogs/2026/jun/19/2026-06-19-13-11-test/README.md" | grep -Eq '^(layer|mode|workflow): '; then
+  fail "smoke fixture contains durable classification metadata"
+fi
+
+bash -c 'cd "$1" && shift && "$@"' sh "$REPO" \
+  bash scripts/00.chat/session-log/check-commit-prerequisites/script.sh \
+  >"$TMP_ROOT/out"
+
+grep -q 'Commit prerequisites are present.' "$TMP_ROOT/out" \
+  || fail "commit prerequisites did not pass with prose directory reference"
+
+if grep -q 'scripts/00.chat/ is missing' "$TMP_ROOT/out"; then
+  fail "directory prose reference was treated as a missing script"
+fi
+
+echo "commit prerequisites smoke test passed."

package/scripts/00.chat/session-log/check-commitlog-deletions/README.md

@@ -0,0 +1,90 @@
+<!-- agentic-artifact:
+  schema: agentic-artifact/v2
+  id: chat.script.session-log.check-commitlog-deletions.readme
+  version: 1
+  status: active
+  layer: 00.chat
+  domain: session-log
+  disciplines:
+  - agentic
+  kind: capability-readme
+  purpose: Explain how the harness protects commit logs that record committed work.
+  portability:
+    class: required
+    targets:
+    - llm-workbench
+  used_by:
+  - id: chat.script.session-log.check-commitlog-deletions
+    path: scripts/00.chat/session-log/check-commitlog-deletions/script.sh
+  - id: chat.script.session-log.check-commitlog-deletions.smoke-test
+    path: scripts/00.chat/session-log/check-commitlog-deletions/smoke-test.sh
+  - id: harness.architecture.adr.0017-organize-scripts-by-owner-domain-and-capability
+-->
+# Check Commit Log Deletions
+
+`script.sh` blocks staged deletion of chat commit logs that contain durable work
+history.
+
+It protects the audit trail. Empty or unsaved session logs can be removed by an
+intentional cleanup commit, but logs that record completed work or are marked for
+retention should not disappear as part of an ordinary task commit.
+
+## Mental Model
+
+Commit logs are not scratch files once they record committed work. They explain
+why a chat branch existed, what was decided, which commits landed, and what
+follow-up may still matter.
+
+This gate watches the staged deletion set. If a staged deletion targets
+`commitLogs/**/README.md`, the script inspects the version from `HEAD` and
+decides whether that log is protected.
+
+## Protected Logs
+
+A deleted log is blocked when the `HEAD` version contains either:
+
+- recorded commit metadata, such as `latest_commit_sha`
+- an entry in `## Commits` that names a commit SHA
+- a retention marker such as `retain: yes`, `preserve: true`, or an
+  `agentic-retain-log` style marker
+
+## Allowed Deletions
+
+Deletion is allowed when the staged log appears empty of committed work and has
+no retention marker. This supports cleanup of abandoned startup logs or other
+bookkeeping-only artifacts.
+
+## What This Does Not Do
+
+- It does not delete files itself.
+- It does not restore protected logs.
+- It does not inspect non-README files.
+- It does not judge whether an allowed deletion is wise.
+- It does not replace human review of cleanup commits.
+
+## Validation
+
+`smoke-test.sh` creates a throwaway repo with three logs:
+
+- one with a recorded commit
+- one empty log
+- one retained log
+
+It verifies that recorded and retained logs are blocked, while an empty-only log
+deletion passes.
+
+Run the canonical smoke test with:
+
+```bash
+bash scripts/00.chat/session-log/check-commitlog-deletions/smoke-test.sh
+```
+
+## Compatibility
+
+The old shared path remains available:
+
+```bash
+scripts/00.chat/session-log/check-commitlog-deletions/script.sh
+```
+
+That file is now a compatibility wrapper around the canonical implementation.

package/scripts/00.chat/session-log/check-commitlog-deletions/script.sh

@@ -0,0 +1,131 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# agentic-artifact:
+#   schema: agentic-artifact/v2
+#   id: chat.script.session-log.check-commitlog-deletions
+#   version: 1
+#   status: active
+#   layer: 00.chat
+#   domain: session-log
+#   disciplines:
+#   - agentic
+#   kind: script
+#   purpose: Block staged deletion of commit logs that record committed work.
+#   portability:
+#     class: required
+#     targets:
+#     - llm-workbench
+#   used_by:
+#   - id: chat.script.session-log.check-commitlog-deletions.readme
+#     path: scripts/00.chat/session-log/check-commitlog-deletions/README.md
+#   - id: chat.script.session-log.check-commitlog-deletions.smoke-test
+#     path: scripts/00.chat/session-log/check-commitlog-deletions/smoke-test.sh
+#   - id: harness.architecture.adr.0010-protect-commit-logs-with-recorded-work
+#   effects:
+#   - read-only
+usage() {
+  cat <<'EOF'
+Usage:
+  check-commitlog-deletions.sh
+
+Blocks staged deletion of commit logs that record committed work or are
+explicitly marked for retention. Empty, unsaved session logs may be deleted by
+an intentional cleanup commit.
+EOF
+}
+
+if [ "${1:-}" = "-h" ] || [ "${1:-}" = "--help" ]; then
+  usage
+  exit 0
+fi
+
+if [ $# -ne 0 ]; then
+  usage >&2
+  exit 2
+fi
+
+FAILURES=0
+
+fail() {
+  echo "ERROR: $*" >&2
+  FAILURES=$((FAILURES + 1))
+}
+
+staged_deleted_commit_logs() {
+  git diff --cached --name-only --diff-filter=D -- 'commitLogs/**/README.md'
+}
+
+head_content() {
+  local path="$1"
+  git show "HEAD:${path}" 2>/dev/null || true
+}
+
+has_recorded_commit() {
+  local content="$1"
+
+  if printf '%s\n' "$content" | grep -Eq '^latest_commit_sha: +[^[:space:]]+'; then
+    return 0
+  fi
+
+  if printf '%s\n' "$content" | awk '
+    $0 == "## Commits" {
+      in_section = 1
+      next
+    }
+    in_section && /^## / {
+      exit
+    }
+    in_section && /^- Commit: `[^`]+`/ {
+      found = 1
+    }
+    in_section && /^Commit: `[^`]+`/ {
+      found = 1
+    }
+    END {
+      exit found ? 0 : 1
+    }
+  '; then
+    return 0
+  fi
+
+  return 1
+}
+
+has_retention_marker() {
+  local content="$1"
+
+  printf '%s\n' "$content" | grep -Eiq \
+    '^(saved|retain|retained|preserve|preserved|keep|kept): +(yes|true)$|agentic-(save|saved|retain|retained|preserve|preserved|keep|kept)-log'
+}
+
+while IFS= read -r path; do
+  if [ -z "${path// }" ]; then
+    continue
+  fi
+
+  content="$(head_content "$path")"
+
+  if [ -z "${content// }" ]; then
+    fail "cannot inspect deleted commit log from HEAD: $path"
+    continue
+  fi
+
+  if has_recorded_commit "$content"; then
+    fail "cannot delete commit log with recorded commits: $path"
+    continue
+  fi
+
+  if has_retention_marker "$content"; then
+    fail "cannot delete commit log marked for retention: $path"
+    continue
+  fi
+done < <(staged_deleted_commit_logs)
+
+if [ "$FAILURES" -gt 0 ]; then
+  echo "Commit log deletion gate failed." >&2
+  echo "Restore protected logs or remove them from the staged deletion set." >&2
+  exit 1
+fi
+
+echo "Commit log deletion gate passed."

package/scripts/00.chat/session-log/check-commitlog-deletions/smoke-test.sh

@@ -0,0 +1,123 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# agentic-artifact:
+#   schema: agentic-artifact/v2
+#   id: chat.script.session-log.check-commitlog-deletions.smoke-test
+#   version: 1
+#   status: active
+#   layer: 00.chat
+#   domain: session-log
+#   disciplines:
+#   - agentic
+#   kind: script
+#   purpose: Smoke test commit log deletion protection for recorded work.
+#   portability:
+#     class: reusable
+#     targets:
+#     - llm-workbench
+#   used_by:
+#   - id: harness.architecture.adr.0010-protect-commit-logs-with-recorded-work
+#   - id: chat.script.session-log.check-commitlog-deletions.readme
+#     path: scripts/00.chat/session-log/check-commitlog-deletions/README.md
+#   - id: chat.script.session-log.check-commitlog-deletions
+#     path: scripts/00.chat/session-log/check-commitlog-deletions/script.sh
+#   effects:
+#   - writes-files
+#   - commits
+SOURCE_ROOT="$(git rev-parse --show-toplevel)"
+TMP_ROOT="$(mktemp -d "${TMPDIR:-/tmp}/commitlog-deletions-smoke.XXXXXX")"
+
+cleanup() {
+  rm -rf "$TMP_ROOT"
+}
+
+trap cleanup EXIT
+
+fail() {
+  echo "ERROR: $*" >&2
+  exit 1
+}
+
+REPO="$TMP_ROOT/repo"
+mkdir -p "$REPO/scripts/00.chat/session-log/check-commitlog-deletions"
+cp "$SOURCE_ROOT/scripts/00.chat/session-log/check-commitlog-deletions/script.sh" "$REPO/scripts/00.chat/session-log/check-commitlog-deletions/script.sh"
+chmod +x "$REPO/scripts/00.chat/session-log/check-commitlog-deletions/script.sh"
+
+git -C "$REPO" init -q -b main
+git -C "$REPO" config user.name "Smoke Test"
+git -C "$REPO" config user.email "smoke@example.invalid"
+
+COMMITTED_LOG="$REPO/commitLogs/2026/jun/16/committed/README.md"
+EMPTY_LOG="$REPO/commitLogs/2026/jun/16/empty/README.md"
+RETAINED_LOG="$REPO/commitLogs/2026/jun/16/retained/README.md"
+
+mkdir -p "$(dirname "$COMMITTED_LOG")" "$(dirname "$EMPTY_LOG")" "$(dirname "$RETAINED_LOG")"
+
+cat > "$COMMITTED_LOG" <<'EOF'
+# Chat Session: committed
+
+<!-- agentic-session
+latest_commit_sha: abc1234
+-->
+
+## Commits
+
+- Commit: `abc1234`
+EOF
+
+cat > "$EMPTY_LOG" <<'EOF'
+# Chat Session: empty
+
+## Commits
+
+TBD
+EOF
+
+cat > "$RETAINED_LOG" <<'EOF'
+# Chat Session: retained
+
+retain: yes
+
+## Commits
+
+TBD
+EOF
+
+git -C "$REPO" add .
+git -C "$REPO" commit -q -m "add logs"
+
+git -C "$REPO" rm -q "$COMMITTED_LOG" "$EMPTY_LOG" "$RETAINED_LOG"
+
+set +e
+(
+  cd "$REPO"
+  bash scripts/00.chat/session-log/check-commitlog-deletions/script.sh
+) > "$TMP_ROOT/protected.out" 2> "$TMP_ROOT/protected.err"
+PROTECTED_STATUS="$?"
+set -e
+
+if [ "$PROTECTED_STATUS" -eq 0 ]; then
+  fail "protected commit log deletions were allowed"
+fi
+
+if ! grep -q "cannot delete commit log with recorded commits" "$TMP_ROOT/protected.err"; then
+  fail "recorded commit deletion was not reported"
+fi
+
+if ! grep -q "cannot delete commit log marked for retention" "$TMP_ROOT/protected.err"; then
+  fail "retained commit log deletion was not reported"
+fi
+
+git -C "$REPO" restore --staged --worktree -- "$COMMITTED_LOG" "$RETAINED_LOG"
+
+(
+  cd "$REPO"
+  bash scripts/00.chat/session-log/check-commitlog-deletions/script.sh
+) > "$TMP_ROOT/empty-only.out" 2> "$TMP_ROOT/empty-only.err"
+
+if ! grep -q "Commit log deletion gate passed" "$TMP_ROOT/empty-only.out"; then
+  fail "empty-only deletion did not pass"
+fi
+
+echo "commitlog deletion smoke test passed."

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

@@ -0,0 +1,98 @@
+<!-- agentic-artifact:
+  schema: agentic-artifact/v2
+  id: chat.script.session-log.checkpoint-chat-session-log.readme
+  version: 1
+  status: active
+  layer: 00.chat
+  domain: session-log
+  disciplines:
+  - agentic
+  kind: capability-readme
+  purpose: Explain when and how chat session-log bookkeeping is checkpointed as its
+    own commit.
+  portability:
+    class: required
+    targets:
+    - llm-workbench
+  used_by:
+  - id: chat.script.session-log.checkpoint-chat-session-log
+    path: scripts/00.chat/session-log/checkpoint-chat-session-log/script.sh
+  - id: harness.architecture.adr.0017-organize-scripts-by-owner-domain-and-capability
+-->
+# Checkpoint Chat Session Log
+
+`script.sh` commits only the current chat session log as a narrow bookkeeping
+checkpoint.
+
+It exists because task work and session-log bookkeeping are intentionally
+separate. A task commit should contain the actual implementation, documentation,
+or harness change. After that commit is recorded into the session log, the log
+itself becomes dirty. This helper creates the follow-up bookkeeping commit when
+the session log is the only remaining change.
+
+## Mental Model
+
+The session log is part of the audit trail, but it is not the task change
+itself.
+
+The usual rhythm is:
+
+1. make and commit the task change
+2. run `record-chat-commit` to write that task commit into the session log
+3. run `checkpoint-chat-session-log` to commit the session-log update by itself
+
+That gives the Git history two clean boundaries: one for the work, and one for
+the chat record about the work.
+
+## Safety Rule
+
+This helper only checkpoints when the dirty state is limited to the current
+chat session log.
+
+It refuses to run if:
+
+- any unrelated file is staged
+- any unrelated file is dirty
+- the current branch is not a `chat/*` branch
+- the matching session log cannot be found
+
+That refusal is the point. A bookkeeping checkpoint should never quietly include
+task files, unrelated docs, generated output, or another chat's log.
+
+## Usage
+
+```bash
+checkpoint-chat-session-log.sh [--dry-run] [message]
+```
+
+- `--dry-run`: show what would be committed without staging or committing.
+- `message`: optional commit message. The default is
+  `chore(session): checkpoint chat log`.
+
+## What This Does
+
+- derives the session id from the current `chat/*` branch
+- finds the matching session log
+- verifies there are no unrelated staged or dirty files
+- stages only the current session log
+- commits only that session log
+
+## What This Does Not Do
+
+- It does not record a task commit in the session log.
+- It does not inspect whether the task commit itself was good.
+- It does not push anything.
+- It does not merge anything.
+- It does not allow mixed bookkeeping and task changes.
+
+## Compatibility
+
+The governed runner still approves the old path:
+
+```bash
+scripts/00.chat/session-log/checkpoint-chat-session-log/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.