Merge f3dfacf93e into 40ff01b987

.agents/friction-log/README.md

@@ -0,0 +1,34 @@
+# Friction log
+
+Friction hit while working in this repository, one directory per item:
+
+```
+<id>/
+  friction.md   the write-up
+  artifacts/    optional, whatever reproduces it
+```
+
+Reporting an entry gives it an owner. The write-up then carries an `issue:` link and mirrors what happens
+to it. The whole directory is deleted once the friction is resolved. Every entry left here is still
+outstanding, including friction in dependencies.
+
+Do not maintain an index here. This directory is the index.
+
+## Logging Friction
+
+```sh
+frog list    # what is already known
+frog log     # add one
+```
+
+`frog log` writes the sections to fill in. Each id is when the friction was hit plus its title, so
+the directory reads oldest-first.
+
+Put anything that reproduces the friction in that entry's `artifacts/` and reference it from the
+write-up. The next reader runs the reproduction instead of rebuilding it.
+
+## For Agents
+
+These rules live in `CLAUDE.md`, which `AGENTS.md` points at, so amend them there rather than duplicating them into `AGENTS.md`.
+
+Managed by [Frog](https://github.com/wevm/frog).

.agents/friction-log/config.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://unpkg.com/frog/schema.json",
+  "inbound": {
+    "enabled": true
+  }
+}

.github/ISSUE_TEMPLATE/friction.yml

@@ -0,0 +1,34 @@
+name: Friction
+description: Something about this project cost you time.
+labels: [friction]
+body:
+  - type: textarea
+    attributes:
+      label: Expected Behavior
+      description: Describe what should happen.
+    validations:
+      required: false
+  - type: textarea
+    attributes:
+      label: Current Behavior
+      description: Describe what happens instead.
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Possible Solution
+      description: Optional. Suggest a fix or a reason for the friction.
+    validations:
+      required: false
+  - type: textarea
+    attributes:
+      label: Minimal Reproducible Example
+      description: Add a minimal reproducible example under `artifacts/`, or an unambiguous set of steps to reproduce this. Include code where relevant.
+    validations:
+      required: false
+  - type: textarea
+    attributes:
+      label: Context
+      description: Describe how this affected you, and what you were trying to accomplish.
+    validations:
+      required: false

.github/workflows/friction-log.yml

@@ -0,0 +1,39 @@
+name: Friction Log
+on:
+  push:
+    branches: [litellm_internal_staging]
+  issues:
+    types: [closed, reopened]
+  workflow_dispatch:
+  schedule:
+    - cron: '0 0 * * *'
+
+concurrency:
+  group: friction-log
+  cancel-in-progress: false
+
+permissions: {}
+
+jobs:
+  friction-log:
+    name: Friction Log
+    if: github.event_name != 'issues' || github.event.issue.user.login == 'github-actions[bot]'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      issues: write
+      pull-requests: write
+
+    steps:
+      - name: Clone repository
+        uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
+        with:
+          persist-credentials: false
+          ref: ${{ github.sha }}
+
+      - name: Report and reconcile frictions
+        uses: wevm/frog/action@702c4eadefe175a208290a99c36e7f4ac1390e53 # frog@1.1.0
+        with:
+          issue-author: github-actions[bot]
+          branch: frog-sync
+          version: 1.1.0

CLAUDE.md

@@ -102,6 +102,16 @@ Follow these coding conventions for new/updated code (a three-line fix in a lega
 
 Follow conventional commits for commit names and PR titles
 
+Log papercuts and friction you hit in this repository (tooling, docs, APIs, tests, conventions) with `frog log`, and run `frog list` first so you don't re-report something already known. Only repo-level friction belongs in `.agents/friction-log/`, not global, system, or agent-harness friction. If `frog` is missing, install the pinned release instead of piping the installer into a shell (pick the asset matching your platform from https://github.com/wevm/frog/releases/tag/frog@1.1.0):
+
+```sh
+ver=1.1.0
+asset=frog-linux-x64-glibc-baseline.gz
+curl -fsSLO "https://github.com/wevm/frog/releases/download/frog@$ver/$asset"
+curl -fsSL "https://github.com/wevm/frog/releases/download/frog@$ver/SHA256SUMS" | grep "$asset" | sha256sum -c -
+gunzip -c "$asset" > ~/.local/bin/frog && chmod +x ~/.local/bin/frog
+```
+
 ## Think Before Coding
 
 **Don't assume. Don't hide confusion. Surface tradeoffs**