erk 0.4.5__py3-none-any.whl

erk/data/claude/skills/erk-diff-analysis/references/commit-message-prompt.md

@@ -0,0 +1,78 @@
+You are a commit message generator. Analyze the provided git diff and return ONLY a commit message.
+
+## Analysis Principles
+
+Analyze the diff following these principles:
+
+- **Be concise and strategic** - focus on significant changes
+- **Use component-level descriptions** - reference modules/components, not individual functions
+- **Highlight breaking changes prominently**
+- **Note test coverage patterns**
+- **Use relative paths from repository root**
+
+## Level of Detail
+
+- Focus on architectural and component-level impact
+- Keep "Key Changes" to 3-5 major items
+- Group related changes together
+- Skip minor refactoring, formatting, or trivial updates
+
+## Output Format
+
+```
+[Clear one-line PR title describing the change]
+
+[2-3 sentence summary explaining what changed and why. State what the branch does (feature/fix/refactor) and highlight key changes briefly.]
+
+## Files Changed
+
+### Added (N files)
+- `path/to/file.py` - Brief purpose (one line)
+
+### Modified (N files)
+- `path/to/file.py` - What area changed (component level)
+
+### Deleted (N files)
+- `path/to/file.py` - Why removed (strategic reason)
+
+## Key Changes
+
+- [3-5 high-level component/architectural changes]
+- Strategic change description focusing on purpose and impact
+- Focus on what capabilities changed, not implementation details
+
+## User Experience
+[Only include this section if changes affect user-facing behavior: CLI commands, prompts, output, workflows]
+
+**Before:**
+```
+
+[Show the old user experience - what command they ran and what happened]
+
+```
+
+**After:**
+```
+
+[Show the new user experience - same scenario with new behavior]
+
+```
+
+[Optional 1-2 sentence explanation of the improvement]
+
+## Critical Notes
+[Only if there are breaking changes, security concerns, or important warnings - 1-2 bullets max]
+```
+
+## Rules
+
+- **IMPORTANT**: Output the commit message directly. Do NOT wrap your response in code fences or markdown blocks.
+- Output ONLY the commit message (no preamble, no explanation, no commentary)
+- NO Claude attribution or footer (NEVER add "Generated with Claude Code" or similar)
+- NO metadata headers (NEVER add `**Author:**`, `**Plan:**`, `Closes #N`, or similar)
+- Use relative paths from repository root
+- Be concise (15-40 lines total, shorter if no User Experience section)
+- First line = PR title, rest = PR body
+- Avoid function-level details unless critical
+- Maximum 5 key changes
+- Only include Critical Notes if necessary

erk/data/claude/skills/learned-docs/SKILL.md

@@ -0,0 +1,362 @@
+---
+name: learned-docs
+description: This skill should be used when writing, modifying, or reorganizing
+  documentation in docs/learned/. Use when creating new documents, updating frontmatter,
+  choosing categories, creating index files, updating routing tables, or moving
+  files between categories. Essential for maintaining consistent documentation structure.
+---
+
+# Learned Documentation Guide
+
+Overview: `docs/learned/` contains agent-focused documentation with:
+
+- YAML frontmatter for routing and discovery
+- Hierarchical category organization (categories listed in index below)
+- Index files for category navigation
+- Routing tables in AGENTS.md
+
+## Document Registry (Auto-Generated)
+
+@docs/learned/index.md
+
+## Frontmatter Requirements
+
+Every markdown file (except index.md) MUST have:
+
+```yaml
+---
+title: Document Title
+read_when:
+  - "first condition"
+  - "second condition"
+---
+```
+
+### Required Fields
+
+| Field       | Type         | Purpose                                    |
+| ----------- | ------------ | ------------------------------------------ |
+| `title`     | string       | Human-readable title for index tables      |
+| `read_when` | list[string] | Conditions when agent should read this doc |
+
+### Writing Effective read_when Values
+
+- Use gerund phrases: "creating a plan", "styling CLI output"
+- Be specific: "fixing merge conflicts in tests" not "tests"
+- Include 2-4 conditions covering primary use cases
+- Think: "An agent should read this when they are..."
+
+Good:
+
+```yaml
+read_when:
+  - "creating or closing plans"
+  - "understanding plan states"
+  - "working with .impl/ folders"
+```
+
+Bad:
+
+```yaml
+read_when:
+  - "plans" # Too vague
+  - "the user asks" # Not descriptive
+```
+
+## Documentation Structure
+
+**Read the master index for current categories and documents:**
+
+`docs/learned/index.md`
+
+The index contains:
+
+- All category paths and descriptions
+- Root-level documents
+- Document listings with "Read when..." conditions
+
+## Category Placement Guidelines
+
+1. **Match by topic** - Does the doc clearly fit one category? (see index above for categories)
+2. **Match by related docs** - Are similar docs already in a category?
+3. **When unclear** - Place at root level; categorize later when patterns emerge
+4. **Create new category** - When 3+ related docs exist at root level
+
+### Distinguishing cli/ vs architecture/
+
+This is the most common confusion:
+
+- **cli/**: Patterns for **building CLI commands** - how users interact with the tool
+  - Fast-path patterns (skipping expensive ops)
+  - Output formatting and styling
+  - Script mode behavior
+  - Command organization
+
+- **architecture/**: **Internal implementation patterns** - how the code works
+  - Gateway ABCs and dependency injection
+  - Dry-run via wrapper classes
+  - Shell integration constraints
+  - Protocol vs ABC decisions
+
+## Document Structure Template
+
+```markdown
+---
+title: [Clear Document Title]
+read_when:
+  - "[first condition]"
+  - "[second condition]"
+---
+
+# [Title Matching Frontmatter]
+
+[1-2 sentence overview]
+
+## [Main Content Sections]
+
+[Organized content with clear headers]
+
+## Related Topics
+
+- [Link to related docs](../category/doc.md) - Brief description
+```
+
+## Index File Template
+
+Each category has an `index.md` following this pattern:
+
+```markdown
+---
+title: [Category] Documentation
+read_when:
+  - "[when to browse this category]"
+---
+
+# [Category] Documentation
+
+[Brief category description]
+
+## Quick Navigation
+
+| When you need to... | Read this        |
+| ------------------- | ---------------- |
+| [specific task]     | [doc.md](doc.md) |
+
+## Documents in This Category
+
+### [Document Title]
+
+**File:** [doc.md](doc.md)
+
+[1-2 sentence description]
+
+## Related Topics
+
+- [Other Category](../other/) - Brief relevance
+```
+
+## Code in Documentation
+
+**Critical rule**: NEVER embed Python functions that process erk data or encode business logic.
+
+### Why This Matters
+
+Embedded Python code in documentation:
+
+- Is NOT under test - it silently goes stale
+- Causes bugs when agents copy outdated patterns
+- Encodes business assumptions (field names, conventions) that can change
+- Creates maintenance burden requiring docs-code sync
+
+PR #2681 demonstrated this: an agent copied incorrect scratch directory paths from documentation because the docs hadn't been updated when the implementation changed.
+
+### The "Simple Function" Trap
+
+Even "simple" functions are dangerous. A one-liner like:
+
+```python
+# DANGEROUS - encodes `agent-` prefix convention
+files = [f for f in dir.glob("*.jsonl") if not f.name.startswith("agent-")]
+```
+
+Embeds a naming convention that could change. When it does, the docs become a source of bugs.
+
+### What to REMOVE (Aggressive Stance)
+
+Remove ALL Python `def` functions that:
+
+- Process session logs, JSONL, or erk data
+- Encode path patterns or naming conventions
+- Filter, parse, or transform erk-specific data
+- Implement algorithms that exist (or could exist) in production
+- Show "how to" implementation patterns for erk internals
+
+**Even if the function doesn't exist in production today**, it could be added later, creating divergence.
+
+### What to KEEP (Narrow Exceptions)
+
+- **JSON/YAML format examples**: Showing data structure, not processing code
+- **External library patterns**: Click commands, pytest fixtures, Rich tables (teaching third-party APIs)
+- **Anti-pattern demonstrations**: Code explicitly marked "WRONG" or "DON'T DO THIS"
+- **Shell/bash commands**: `ls`, `jq`, `grep` for operational tasks
+- **Type definitions**: Dataclass/TypedDict showing structure (not methods)
+
+### Decision Test
+
+Before keeping a Python code block, ask:
+
+1. Does it contain a `def` statement? → Probably REMOVE
+2. Does it process erk-specific data? → REMOVE
+3. Does it encode a convention (field name, path pattern, prefix)? → REMOVE
+4. Is it teaching a third-party API (Click, pytest, Rich)? → KEEP
+5. Is it showing data FORMAT (not processing)? → KEEP
+
+### Replacement Format
+
+When removing code, replace with:
+
+1. **Prose description** of what the operation does
+2. **Source pointer** to canonical implementation
+3. **CLI command** if one exists for agents to use
+
+**Before (BAD)**:
+
+````markdown
+```python
+def find_session_logs(project_dir: Path) -> list[Path]:
+    """Find all main session logs (exclude agent logs)."""
+    return [
+        f for f in project_dir.glob("*.jsonl")
+        if f.is_file() and not f.name.startswith("agent-")
+    ]
+```
+````
+
+**After (GOOD)**:
+
+```markdown
+Main session logs are `.jsonl` files that don't start with `agent-`. Agent
+subprocess logs use the `agent-<id>.jsonl` naming convention.
+
+To list sessions for a project, use:
+erk exec list-sessions
+
+See `preprocess_session.py` for the canonical implementation.
+```
+
+### Source Pointer Rules
+
+- Point to source file path: `package/module.py`
+- NEVER include line numbers (they go stale)
+- Use backticks for file paths
+- Prefer CLI commands over source pointers when available
+
+## Reorganizing Documentation
+
+When moving files between categories:
+
+### Step 1: Move Files with git mv
+
+```bash
+cd docs/learned
+git mv old-location/doc.md new-category/doc.md
+```
+
+### Step 2: Update Cross-References
+
+Find all references to moved files:
+
+```bash
+grep -r "old-filename.md" docs/learned/
+```
+
+Update relative links:
+
+- Same category: `[doc.md](doc.md)`
+- Different category: `[doc.md](../category/doc.md)`
+- To category index: `[Category](../category/)`
+
+### Step 3: Update Index Files
+
+Update Quick Navigation tables in affected index files.
+
+### Step 4: Update AGENTS.md
+
+If the doc was in the routing table, update the path.
+
+### Step 5: Validate
+
+Run `make fast-ci` to catch broken links and formatting issues.
+
+## Updating Routing Tables
+
+AGENTS.md contains the Quick Routing Table for agent navigation.
+
+### When to Add Entries
+
+- New category additions
+- High-frequency tasks
+- Tasks where wrong approach is common
+
+### Entry Format
+
+```markdown
+| [Task description] | → [Link or skill] |
+```
+
+Examples:
+
+- `| Understand project architecture | → [Architecture](docs/learned/architecture/) |`
+- `| Write Python code | → Load \`dignified-python\` skill FIRST |`
+
+## Validation
+
+Run before committing:
+
+```bash
+make fast-ci
+```
+
+This validates:
+
+- YAML frontmatter syntax
+- Required fields present
+- Markdown formatting (prettier)
+
+## ⚠️ Generated Files - Do Not Edit Directly
+
+The following files are **auto-generated** from frontmatter metadata:
+
+| File                               | Source                     |
+| ---------------------------------- | -------------------------- |
+| `docs/learned/index.md`            | Frontmatter from all docs  |
+| `docs/learned/<category>/index.md` | Frontmatter from category  |
+| `docs/learned/tripwires.md`        | `tripwires:` field in docs |
+
+**Never edit these files directly.** Changes will be overwritten.
+
+### Workflow for Changes
+
+1. **Edit the source frontmatter** in the relevant documentation file(s)
+2. **Run sync**: `erk docs sync`
+3. **Verify changes** in the generated files
+4. **Commit both** the source and generated files
+
+### Adding a New Tripwire
+
+To add a tripwire rule:
+
+1. Add to the `tripwires:` field in the relevant doc's frontmatter:
+   ```yaml
+   tripwires:
+     - action: "doing something dangerous"
+       warning: "Do this instead."
+   ```
+2. Run `erk docs sync` to regenerate `tripwires.md`
+
+## Quick Reference
+
+- Full navigation: [docs/learned/guide.md](docs/learned/guide.md)
+- Category index: [docs/learned/index.md](docs/learned/index.md)
+- Regenerate indexes: `erk docs sync`
+- Run validation: `make fast-ci`

erk/data/github/actions/setup-claude-erk/action.yml

@@ -0,0 +1,11 @@
+name: "Setup Erk"
+description: "Install erk tools (assumes container has uv and claude preinstalled)"
+
+runs:
+  using: "composite"
+  steps:
+    - name: Install erk
+      shell: bash
+      run: |
+        cd $GITHUB_WORKSPACE
+        uv tool install --from . --with ./packages/erk-shared erk

erk/data/github/prompts/dignified-python-review.md

@@ -0,0 +1,125 @@
+REPO: {{ github.repository }}
+PR NUMBER: {{ github.event.pull_request.number }}
+
+## Task
+
+Review Python code changes for adherence to dignified-python standards.
+
+## Step 1: Load the Dignified Python Standards
+
+Read these skill files from the repository:
+
+1. .claude/skills/dignified-python/SKILL.md (routing and version detection)
+2. .claude/skills/dignified-python/dignified-python-core.md (LBYL, exceptions, paths, imports, DI, performance)
+3. .claude/skills/dignified-python/cli-patterns.md (Click best practices)
+4. .claude/skills/dignified-python/subprocess.md (subprocess handling)
+
+## Step 2: Get Existing Review Comment
+
+Fetch the existing review comment to preserve the activity log:
+
+```
+gh pr view {{ github.event.pull_request.number }} --json comments --jq '.comments[] | select(.body | contains("<!-- dignified-python-review -->")) | .body'
+```
+
+If a comment exists, extract the Activity Log section (everything after `### Activity Log`). You will append to this log.
+
+## Step 3: Get the Python Diff
+
+```
+gh pr diff {{ github.event.pull_request.number }} --name-only | grep '\.py$'
+gh pr diff {{ github.event.pull_request.number }}
+```
+
+## Step 3b: Identify Changed Lines
+
+For each Python file, determine which lines were actually modified (not just context):
+
+- Lines starting with `+` in the diff are additions/modifications
+- Lines starting with ` ` (space) are unchanged context
+
+For the `__all__` / re-export rule specifically:
+
+- If `__all__` appears on a `+` line → Flag as violation (actively being modified)
+- If `__all__` only appears in context lines → Skip (pre-existing, not being modified)
+
+This allows file moves/refactors to pass while catching active modifications.
+
+## Step 4: Analyze Code
+
+Check each Python file against dignified-python rules:
+
+- LBYL over EAFP (no try/except for control flow)
+- Exception handling (no silent swallowing, log at boundaries)
+- Path operations (exists before resolve)
+- Import organization (module-level, absolute, no re-exports)
+- No default parameter values
+- Dependency injection with ABC
+- Frozen dataclasses
+
+**For `__all__` / re-exports:**
+
+- Only flag if `__all__` appears in the **changed lines** (Step 3b analysis)
+- Skip if `__all__` is pre-existing and unchanged in this PR
+
+## Step 5: Post Inline Comments
+
+**IMPORTANT: You MUST post an inline comment for EACH violation found.**
+
+```
+erk exec post-pr-inline-comment \
+  --pr-number {{ github.event.pull_request.number }} \
+  --path "path/to/file.py" \
+  --line LINE_NUMBER \
+  --body "**Dignified Python**: [rule violated] - [fix suggestion]"
+```
+
+## Step 6: Post Summary Comment
+
+**IMPORTANT: All timestamps MUST be in Pacific Time (PT), NOT UTC.**
+
+Get the current Pacific time timestamp by running this command:
+
+```
+TZ='America/Los_Angeles' date '+%Y-%m-%d %H:%M:%S'
+```
+
+Use this timestamp (with " PT" suffix) for both "Last updated" and Activity Log entries.
+
+Post/update the summary comment:
+
+```
+erk exec post-or-update-pr-summary \
+  --pr-number {{ github.event.pull_request.number }} \
+  --marker "<!-- dignified-python-review -->" \
+  --body "SUMMARY_TEXT"
+```
+
+Summary format (preserve existing Activity Log entries and prepend new entry):
+
+```
+<!-- dignified-python-review -->
+
+## ✅ Dignified Python Review   (use ✅ if 0 issues, ❌ if 1+ issues)
+
+**Last updated:** YYYY-MM-DD HH:MM:SS PT
+
+Found X issues across Y files. Inline comments posted for each.
+
+### Files Reviewed
+- `file.py`: N issues
+
+---
+
+### Activity Log
+- **YYYY-MM-DD HH:MM:SS PT**: [Brief description of this review's findings]
+- [Previous log entries preserved here...]
+```
+
+Activity log entry examples:
+
+- "Found 2 issues (LBYL violation in x.py, inline import in y.py)"
+- "All issues resolved"
+- "False positive dismissed: CLI error boundary pattern"
+
+Keep the last 10 log entries maximum.

erk/data/github/workflows/dignified-python-review.yml

@@ -0,0 +1,61 @@
+# Claude Code CI workflow
+# See docs/learned/ci/containerless-ci.md for native tool installation details
+name: dignified-python-review
+
+on:
+  pull_request:
+    types: [opened, synchronize]
+    paths:
+      - "**/*.py"
+
+jobs:
+  dignified-review:
+    if: github.event.pull_request.draft != true
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      contents: read
+      pull-requests: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Install Claude Code
+        uses: ./.github/actions/setup-claude-code
+
+      - name: Install erk
+        run: uv tool install --from . --with ./packages/erk-shared erk
+
+      - name: Prepare prompt
+        shell: bash
+        run: |
+          # Read prompt file and substitute variables
+          PROMPT=$(cat .github/prompts/dignified-python-review.md)
+          PROMPT="${PROMPT//\{\{ github.repository \}\}/${{ github.repository }}}"
+          PROMPT="${PROMPT//\{\{ github.event.pull_request.number \}\}/${{ github.event.pull_request.number }}}"
+
+          # Write to temp file for claude to read
+          echo "$PROMPT" > /tmp/dignified-python-prompt.md
+          echo "Prompt prepared with PR #${{ github.event.pull_request.number }}"
+
+      - name: Run Dignified Python Review
+        env:
+          CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          # Using sonnet for better analysis accuracy. Haiku missed inline import
+          # violations in PR #3980 - see https://github.com/dagster-io/erk/pull/3980
+          claude --print \
+            --model claude-sonnet-4-5 \
+            --allowedTools 'Bash(gh:*),Bash(erk exec:*),Read(*)' \
+            --dangerously-skip-permissions \
+            --output-format stream-json \
+            --verbose \
+            "$(cat /tmp/dignified-python-prompt.md)"