chore: beads init

.beads/.gitignore

@@ -0,0 +1,73 @@
+# Dolt database (managed by Dolt, not git)
+dolt/
+embeddeddolt/
+
+# Runtime files
+bd.sock
+bd.sock.startlock
+sync-state.json
+last-touched
+.exclusive-lock
+
+# Daemon runtime (lock, log, pid)
+daemon.*
+
+# Interactions log (runtime, not versioned)
+interactions.jsonl
+
+# Push state (runtime, per-machine)
+push-state.json
+
+# Lock files (various runtime locks)
+*.lock
+
+# Credential key (encryption key for federation peer auth — never commit)
+.beads-credential-key
+
+# Local version tracking (prevents upgrade notification spam after git ops)
+.local_version
+
+# Worktree redirect file (contains relative path to main repo's .beads/)
+# Must not be committed as paths would be wrong in other clones
+redirect
+
+# Sync state (local-only, per-machine)
+# These files are machine-specific and should not be shared across clones
+.sync.lock
+export-state/
+export-state.json
+
+# Ephemeral store (SQLite - wisps/molecules, intentionally not versioned)
+ephemeral.sqlite3
+ephemeral.sqlite3-journal
+ephemeral.sqlite3-wal
+ephemeral.sqlite3-shm
+
+# Dolt server management (auto-started by bd)
+dolt-server.pid
+dolt-server.log
+dolt-server.lock
+dolt-server.port
+dolt-server.activity
+
+# Corrupt backup directories (created by bd doctor --fix recovery)
+*.corrupt.backup/
+
+# Backup data (auto-exported JSONL, local-only)
+backup/
+
+# Per-project environment file (Dolt connection config, GH#2520)
+.env
+
+# Legacy files (from pre-Dolt versions)
+*.db
+*.db?*
+*.db-journal
+*.db-wal
+*.db-shm
+db.sqlite
+bd.db
+# NOTE: Do NOT add negation patterns here.
+# They would override fork protection in .git/info/exclude.
+# Config files (metadata.json, config.yaml) are tracked by git by default
+# since no pattern above ignores them.

.beads/README.md

@@ -0,0 +1,81 @@
+# Beads - AI-Native Issue Tracking
+
+Welcome to Beads! This repository uses **Beads** for issue tracking - a modern, AI-native tool designed to live directly in your codebase alongside your code.
+
+## What is Beads?
+
+Beads is issue tracking that lives in your repo, making it perfect for AI coding agents and developers who want their issues close to their code. No web UI required - everything works through the CLI and integrates seamlessly with git.
+
+**Learn more:** [github.com/steveyegge/beads](https://github.com/steveyegge/beads)
+
+## Quick Start
+
+### Essential Commands
+
+```bash
+# Create new issues
+bd create "Add user authentication"
+
+# View all issues
+bd list
+
+# View issue details
+bd show <issue-id>
+
+# Update issue status
+bd update <issue-id> --claim
+bd update <issue-id> --status done
+
+# Sync with Dolt remote
+bd dolt push
+```
+
+### Working with Issues
+
+Issues in Beads are:
+- **Git-native**: Stored in Dolt database with version control and branching
+- **AI-friendly**: CLI-first design works perfectly with AI coding agents
+- **Branch-aware**: Issues can follow your branch workflow
+- **Always in sync**: Auto-syncs with your commits
+
+## Why Beads?
+
+✨ **AI-Native Design**
+- Built specifically for AI-assisted development workflows
+- CLI-first interface works seamlessly with AI coding agents
+- No context switching to web UIs
+
+🚀 **Developer Focused**
+- Issues live in your repo, right next to your code
+- Works offline, syncs when you push
+- Fast, lightweight, and stays out of your way
+
+🔧 **Git Integration**
+- Automatic sync with git commits
+- Branch-aware issue tracking
+- Dolt-native three-way merge resolution
+
+## Get Started with Beads
+
+Try Beads in your own projects:
+
+```bash
+# Install Beads
+curl -sSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
+
+# Initialize in your repo
+bd init
+
+# Create your first issue
+bd create "Try out Beads"
+```
+
+## Learn More
+
+- **Documentation**: [github.com/steveyegge/beads/docs](https://github.com/steveyegge/beads/tree/main/docs)
+- **Quick Start Guide**: Run `bd quickstart`
+- **Examples**: [github.com/steveyegge/beads/examples](https://github.com/steveyegge/beads/tree/main/examples)
+
+---
+
+*Beads: Issue tracking that moves at the speed of thought* ⚡

.beads/config.yaml

@@ -0,0 +1,56 @@
+# Beads Configuration File
+# This file configures default behavior for all bd commands in this repository
+# All settings can also be set via environment variables (BD_* prefix)
+# or overridden with command-line flags
+
+# Issue prefix for this repository (used by bd init)
+# If not set, bd init will auto-detect from directory name
+# Example: issue-prefix: "myproject" creates issues like "myproject-1", "myproject-2", etc.
+# issue-prefix: ""
+
+# Use no-db mode: JSONL-only, no Dolt database
+# When true, bd will use .beads/issues.jsonl as the source of truth
+# no-db: false
+
+# Enable JSON output by default
+# json: false
+
+# Feedback title formatting for mutating commands (create/update/close/dep/edit)
+# 0 = hide titles, N > 0 = truncate to N characters
+# output:
+#   title-length: 255
+
+# Default actor for audit trails (overridden by BEADS_ACTOR or --actor)
+# actor: ""
+
+# Export events (audit trail) to .beads/events.jsonl on each flush/sync
+# When enabled, new events are appended incrementally using a high-water mark.
+# Use 'bd export --events' to trigger manually regardless of this setting.
+# events-export: false
+
+# Multi-repo configuration (experimental - bd-307)
+# Allows hydrating from multiple repositories and routing writes to the correct database
+# repos:
+#   primary: "."  # Primary repo (where this database lives)
+#   additional:   # Additional repos to hydrate from (read-only)
+#     - ~/beads-planning  # Personal planning repo
+#     - ~/work-planning   # Work planning repo
+
+# JSONL backup (periodic export for off-machine recovery)
+# Auto-enabled when a git remote exists. Override explicitly:
+# backup:
+#   enabled: false     # Disable auto-backup entirely
+#   interval: 15m      # Minimum time between auto-exports
+#   git-push: false    # Disable git push (export locally only)
+#   git-repo: ""       # Separate git repo for backups (default: project repo)
+
+# Integration settings (access with 'bd config get/set')
+# These are stored in the database, not in this file:
+# - jira.url
+# - jira.project
+# - linear.url
+# - linear.api-key
+# - github.org
+# - github.repo
+
+sync.remote: "git+ssh://gitea@code.m3ta.dev/m3tam3re/nixpkgs.git"

.beads/hooks/post-checkout

@@ -0,0 +1,24 @@
+#!/usr/bin/env sh
+# --- BEGIN BEADS INTEGRATION v1.0.2 ---
+# This section is managed by beads. Do not remove these markers.
+if command -v bd >/dev/null 2>&1; then
+  export BD_GIT_HOOK=1
+  _bd_timeout=${BEADS_HOOK_TIMEOUT:-300}
+  if command -v timeout >/dev/null 2>&1; then
+    timeout "$_bd_timeout" bd hooks run post-checkout "$@"
+    _bd_exit=$?
+    if [ $_bd_exit -eq 124 ]; then
+      echo >&2 "beads: hook 'post-checkout' timed out after ${_bd_timeout}s — continuing without beads"
+      _bd_exit=0
+    fi
+  else
+    bd hooks run post-checkout "$@"
+    _bd_exit=$?
+  fi
+  if [ $_bd_exit -eq 3 ]; then
+    echo >&2 "beads: database not initialized — skipping hook 'post-checkout'"
+    _bd_exit=0
+  fi
+  if [ $_bd_exit -ne 0 ]; then exit $_bd_exit; fi
+fi
+# --- END BEADS INTEGRATION v1.0.2 ---

.beads/hooks/post-merge

@@ -0,0 +1,24 @@
+#!/usr/bin/env sh
+# --- BEGIN BEADS INTEGRATION v1.0.2 ---
+# This section is managed by beads. Do not remove these markers.
+if command -v bd >/dev/null 2>&1; then
+  export BD_GIT_HOOK=1
+  _bd_timeout=${BEADS_HOOK_TIMEOUT:-300}
+  if command -v timeout >/dev/null 2>&1; then
+    timeout "$_bd_timeout" bd hooks run post-merge "$@"
+    _bd_exit=$?
+    if [ $_bd_exit -eq 124 ]; then
+      echo >&2 "beads: hook 'post-merge' timed out after ${_bd_timeout}s — continuing without beads"
+      _bd_exit=0
+    fi
+  else
+    bd hooks run post-merge "$@"
+    _bd_exit=$?
+  fi
+  if [ $_bd_exit -eq 3 ]; then
+    echo >&2 "beads: database not initialized — skipping hook 'post-merge'"
+    _bd_exit=0
+  fi
+  if [ $_bd_exit -ne 0 ]; then exit $_bd_exit; fi
+fi
+# --- END BEADS INTEGRATION v1.0.2 ---

.beads/hooks/pre-commit

@@ -0,0 +1,24 @@
+#!/usr/bin/env sh
+# --- BEGIN BEADS INTEGRATION v1.0.2 ---
+# This section is managed by beads. Do not remove these markers.
+if command -v bd >/dev/null 2>&1; then
+  export BD_GIT_HOOK=1
+  _bd_timeout=${BEADS_HOOK_TIMEOUT:-300}
+  if command -v timeout >/dev/null 2>&1; then
+    timeout "$_bd_timeout" bd hooks run pre-commit "$@"
+    _bd_exit=$?
+    if [ $_bd_exit -eq 124 ]; then
+      echo >&2 "beads: hook 'pre-commit' timed out after ${_bd_timeout}s — continuing without beads"
+      _bd_exit=0
+    fi
+  else
+    bd hooks run pre-commit "$@"
+    _bd_exit=$?
+  fi
+  if [ $_bd_exit -eq 3 ]; then
+    echo >&2 "beads: database not initialized — skipping hook 'pre-commit'"
+    _bd_exit=0
+  fi
+  if [ $_bd_exit -ne 0 ]; then exit $_bd_exit; fi
+fi
+# --- END BEADS INTEGRATION v1.0.2 ---

.beads/hooks/pre-push

@@ -0,0 +1,24 @@
+#!/usr/bin/env sh
+# --- BEGIN BEADS INTEGRATION v1.0.2 ---
+# This section is managed by beads. Do not remove these markers.
+if command -v bd >/dev/null 2>&1; then
+  export BD_GIT_HOOK=1
+  _bd_timeout=${BEADS_HOOK_TIMEOUT:-300}
+  if command -v timeout >/dev/null 2>&1; then
+    timeout "$_bd_timeout" bd hooks run pre-push "$@"
+    _bd_exit=$?
+    if [ $_bd_exit -eq 124 ]; then
+      echo >&2 "beads: hook 'pre-push' timed out after ${_bd_timeout}s — continuing without beads"
+      _bd_exit=0
+    fi
+  else
+    bd hooks run pre-push "$@"
+    _bd_exit=$?
+  fi
+  if [ $_bd_exit -eq 3 ]; then
+    echo >&2 "beads: database not initialized — skipping hook 'pre-push'"
+    _bd_exit=0
+  fi
+  if [ $_bd_exit -ne 0 ]; then exit $_bd_exit; fi
+fi
+# --- END BEADS INTEGRATION v1.0.2 ---

.beads/hooks/prepare-commit-msg

@@ -0,0 +1,24 @@
+#!/usr/bin/env sh
+# --- BEGIN BEADS INTEGRATION v1.0.2 ---
+# This section is managed by beads. Do not remove these markers.
+if command -v bd >/dev/null 2>&1; then
+  export BD_GIT_HOOK=1
+  _bd_timeout=${BEADS_HOOK_TIMEOUT:-300}
+  if command -v timeout >/dev/null 2>&1; then
+    timeout "$_bd_timeout" bd hooks run prepare-commit-msg "$@"
+    _bd_exit=$?
+    if [ $_bd_exit -eq 124 ]; then
+      echo >&2 "beads: hook 'prepare-commit-msg' timed out after ${_bd_timeout}s — continuing without beads"
+      _bd_exit=0
+    fi
+  else
+    bd hooks run prepare-commit-msg "$@"
+    _bd_exit=$?
+  fi
+  if [ $_bd_exit -eq 3 ]; then
+    echo >&2 "beads: database not initialized — skipping hook 'prepare-commit-msg'"
+    _bd_exit=0
+  fi
+  if [ $_bd_exit -ne 0 ]; then exit $_bd_exit; fi
+fi
+# --- END BEADS INTEGRATION v1.0.2 ---

.beads/metadata.json

@@ -0,0 +1,7 @@
+{
+  "database": "dolt",
+  "backend": "dolt",
+  "dolt_mode": "embedded",
+  "dolt_database": "nixpkgs",
+  "project_id": "b57a167a-6526-4211-a6c1-51686e431912"
+}

.gitignore

@@ -45,3 +45,8 @@ flake.lock.bak
 .td-root
 .cache
 .pi*
+
+# Beads / Dolt files (added by bd init)
+.dolt/
+*.db
+.beads-credential-key

AGENTS.md

@@ -1,216 +1,84 @@
-# m3ta-nixpkgs Knowledge Base
+# Agent Instructions
 
-**Generated:** 2026-02-14
+This project uses **bd** (beads) for issue tracking. Run `bd prime` for full workflow context.
-**Commit:** dc2f3b6
-**Branch:** master
 
-## OVERVIEW
+## Quick Reference
-
-Personal Nix flake: custom packages, overlays, NixOS/Home Manager modules, dev shells. Flakes-only (no channels).
-
-## STRUCTURE
-
-```
-.
-├── flake.nix              # Entry: packages, overlays, modules, shells, lib
-├── pkgs/                  # Custom packages (one dir each, callPackage registry)
-├── modules/
-│   ├── nixos/             # System modules (ports.nix)
-│   └── home-manager/      # User modules by category (cli/, coding/, ports.nix)
-├── lib/                   # Shared utilities (ports.nix)
-├── shells/                # Dev environments (default, python, devops)
-├── overlays/mods/         # Package modifications (n8n version bump)
-├── templates/             # Boilerplate for new packages/modules
-├── examples/              # Usage examples
-└── .gitea/workflows/     # CI/CD workflows (nix-update automation)
-```
-
-## WHERE TO LOOK
-
-| Task                 | Location                           | Notes                                 |
-| -------------------- | ---------------------------------- | ------------------------------------- |
-| Add package          | `pkgs/<name>/default.nix`          | Register in `pkgs/default.nix`        |
-| Add NixOS module     | `modules/nixos/<name>.nix`         | Import in `modules/nixos/default.nix` |
-| Add HM module        | `modules/home-manager/<category>/` | Category: cli, coding, or root        |
-| Override nixpkgs pkg | `overlays/mods/<name>.nix`         | Import in `overlays/mods/default.nix` |
-| Add dev shell        | `shells/<name>.nix`                | Register in `shells/default.nix`      |
-| Use port management  | `config.m3ta.ports.get "service"`  | Host-specific via `hostOverrides`     |
-| CI/CD workflows      | `.gitea/workflows/<name>.yml`      | Automated package updates (nix-update) |
-
-## CONVENTIONS
-
-**Formatter**: `nix fmt` before commit (alejandra)
-
-**Naming**:
-
-- Packages: `lowercase-hyphen` (e.g., `hyprpaper-random`)
-- Variables: `camelCase` (e.g., `portHelpers`)
-- Module options: `m3ta.*` namespace
-
-**Imports**: Multi-line, trailing commas:
-
-```nix
-{
-  lib,
-  stdenv,
-  fetchFromGitHub,
-}:
-```
-
-**Modules**: Standard pattern:
-
-```nix
-{ config, lib, pkgs, ... }:
-with lib; let
-  cfg = config.m3ta.myModule;
-in {
-  options.m3ta.myModule = {
-    enable = mkEnableOption "description";
-  };
-  config = mkIf cfg.enable { ... };
-}
-```
-
-**Meta**: Always include all fields:
-
-```nix
-meta = with lib; {
-  description = "...";
-  homepage = "...";
-  license = licenses.mit;
-  platforms = platforms.linux;
-  mainProgram = "...";
-};
-```
-
-## PACKAGE PATTERNS
-
-**Rust**: `rustPlatform.buildRustPackage rec { cargoLock.lockFile = src + "/Cargo.lock"; }`
-
-**Shell**: `writeShellScriptBin "name" ''script''` or `mkDerivation` with custom `installPhase`
-
-**AppImage**: `appimageTools.wrapType2 { ... }`
-
-**Custom fetcher**: `fetchFromGitea { domain = "code.m3ta.dev"; owner = "m3tam3re"; ... }`
-
-## MODULE PATTERNS
-
-**Simple**: `options.cli.name = { enable = mkEnableOption "..."; }; config = mkIf cfg.enable { ... };`
-
-**Multiple**: `config = mkMerge [ (mkIf cfg.x.enable { ... }) (mkIf cfg.y.enable { ... }) ];`
-
-**Shared lib**: `portsLib = import ../../lib/ports.nix { inherit lib; }; portHelpers = portsLib.mkPortHelpers { ... };`
-
-## LIBRARY FUNCTIONS
-
-### `lib.ports`
-
-Port management utilities. See [Port Management](#port-management).
-
-### `lib.agents`
-
-Harness-agnostic agent management. Reads canonical `agent.toml` +
-`system-prompt.md` from the AGENTS flake input and renders tool-specific configs.
-
-**Functions:**
-
-| Function | Purpose |
-|----------|--------|
-| `loadCanonical { agentsInput }` | Load canonical agents from AGENTS flake |
-| `renderForOpencode { pkgs, canonical, modelOverrides }` | Render to OpenCode file-based agents |
-| `renderForClaudeCode { pkgs, canonical, modelOverrides }` | Render to Claude Code agents + settings.json |
-| `renderForPi { pkgs, canonical, modelOverrides, primaryAgent }` | Render to Pi AGENTS.md + SYSTEM.md + agents/ |
-| `renderForTool { pkgs, agentsInput, tool, modelOverrides }` | Dispatch to correct renderer by tool name |
-| `shellHookForTool { pkgs, agentsInput, tool, modelOverrides }` | Generate devShell shellHook (symlinks rendered files) |
-
-### `lib.coding-rules`
-
-Coding rules injection. Generates `coding-rules.json` + symlinks rules from
-the AGENTS repository.
-
-| Function | Purpose |
-|----------|--------|
-| `mkCodingRules { agents, languages, concerns, frameworks, rulesDir }` | Generate rules config + shellHook. `rulesDir` defaults to `.opencode-rules` |
-
-## PORT MANAGEMENT
-
-Central port management: `config.m3ta.ports.get "service"` with host-specific via `hostOverrides`
-
-Generated: `/etc/m3ta/ports.json` (NixOS), `~/.config/m3ta/ports.json` (HM)
-
-## COMMANDS
 
 ```bash
-nix flake check              # Validate flake
+bd ready              # Find available work
-nix fmt                      # Format (alejandra)
+bd show <id>          # View issue details
-nix build .#<pkg>            # Build package
+bd update <id> --claim  # Claim work atomically
-nix flake show               # List outputs
+bd close <id>         # Complete work
-nix develop                  # Enter dev shell
+bd dolt push          # Push beads data to remote
-nix develop .#python         # Python shell
-nix develop .#devops         # DevOps shell
-
-# In dev shell only:
-statix check .               # Lint
-deadnix .                    # Find dead code
 ```
 
-## ANTI-PATTERNS
+## Non-Interactive Shell Commands
 
-| Don't                     | Do Instead                                                          |
+**ALWAYS use non-interactive flags** with file operations to avoid hanging on confirmation prompts.
-| ------------------------- | ------------------------------------------------------------------- |
-| `lib.fakeHash` in commits | Get real hash: `nix build`, copy from error                         |
-| Flat module files         | Organize by category (`cli/`, `coding/`)                            |
-| Hardcode ports            | Use `m3ta.ports` module                                             |
-| Skip meta fields          | Include all: description, homepage, license, platforms, mainProgram |
-| `with pkgs;` in modules   | Explicit `pkgs.package` or `with pkgs; [ ... ]` in lists only       |
 
-## COMMIT FORMAT
+Shell commands like `cp`, `mv`, and `rm` may be aliased to include `-i` (interactive) mode on some systems, causing the agent to hang indefinitely waiting for y/n input.
 
-```
+**Use these forms instead:**
-type: brief description
+```bash
+# Force overwrite without prompting
+cp -f source dest           # NOT: cp source dest
+mv -f source dest           # NOT: mv source dest
+rm -f file                  # NOT: rm file
+
+# For recursive operations
+rm -rf directory            # NOT: rm -r directory
+cp -rf source dest          # NOT: cp -r source dest
 ```
 
-Types: `feat`, `fix`, `docs`, `style`, `refactor`, `chore`
+**Other commands that may prompt:**
+- `scp` - use `-o BatchMode=yes` for non-interactive
+- `ssh` - use `-o BatchMode=yes` to fail instead of prompting
+- `apt-get` - use `-y` flag
+- `brew` - use `HOMEBREW_NO_AUTO_UPDATE=1` env var
 
-## NOTES
+<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:ca08a54f -->
+## Beads Issue Tracker
 
-- **Hash fetching**: Use `lib.fakeHash` initially, build to get real hash
+This project uses **bd (beads)** for issue tracking. Run `bd prime` to see full workflow context and commands.
-- **HM modules**: Category subdirs (`cli/`, `coding/`) have own `default.nix` aggregators
-- **Ports module**: Different for NixOS vs HM (HM adds `generateEnvVars` option)
-- **Overlays**: `modifications` overlay uses `{prev}:` pattern, not `{final, prev}:`
-- **Dev shell tools**: `statix`, `deadnix` only available inside `nix develop`
-- **Automated package updates**: Packages are automatically updated weekly via Gitea Actions using `nix-update`. Review PRs from the automation before merging. For urgent updates, manually run the workflow or update manually.
 
-## Task Management
+### Quick Reference
 
-**td** is an optional task-tracking package. See `docs/packages/td.md` for details.
+```bash
+bd ready              # Find available work
+bd show <id>          # View issue details
+bd update <id> --claim  # Claim work
+bd close <id>         # Complete work
+```
 
-## Agent System Architecture
+### Rules
 
-The agent system uses harness-agnostic canonical definitions stored as
+- Use `bd` for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists
-`agent.toml` + `system-prompt.md` in the AGENTS repository. Renderers in
+- Run `bd prime` for detailed command reference and session close protocol
-`lib/agents.nix` transform these into tool-specific configs at build time.
+- Use `bd remember` for persistent knowledge — do NOT use MEMORY.md files
 
-### How it works
+## Session Completion
 
-1. **Canonical definitions** live in the AGENTS repo as `agent.toml` files
+**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.
-   (one per agent) with shared fields: name, description, mode, systemPrompt,
-   permissions, skills.
-2. **`loadCanonical`** reads all agent definitions from the AGENTS flake input.
-3. **Renderers** produce tool-specific output:
-   - `renderForOpencode` → `*.md` files with YAML frontmatter for `.opencode/agents/`
-   - `renderForClaudeCode` → `.claude/agents/*.md` + `.claude/settings.json` with permission rules
-   - `renderForPi` → `AGENTS.md`, `SYSTEM.md`, `agents/*.md` for Pi's subagent format
-4. **`renderForTool`** dispatches to the correct renderer by tool name
-   (`"opencode"`, `"claude-code"`, or `"pi"`).
-5. **`shellHookForTool`** generates a devShell shellHook that symlinks rendered
-   files into the project directory.
-6. **HM modules** in `modules/home-manager/coding/agents/` handle per-tool
-   Home Manager integration.
 
-### Key files in this repo
+**MANDATORY WORKFLOW:**
 
-- `lib/agents.nix` — renderers, dispatcher, shellHook generator
+1. **File issues for remaining work** - Create issues for anything that needs follow-up
-- `lib/coding-rules.nix` — coding rules injection (`mkCodingRules`)
+2. **Run quality gates** (if code changed) - Tests, linters, builds
-- `modules/home-manager/coding/agents/` — per-tool HM sub-modules (opencode, claude-code, pi)
+3. **Update issue status** - Close finished work, update in-progress items
-- `modules/home-manager/coding/opencode.nix` — OpenCode HM module (slimmed, agents handled separately)
+4. **PUSH TO REMOTE** - This is MANDATORY:
+   ```bash
+   git pull --rebase
+   bd dolt push
+   git push
+   git status  # MUST show "up to date with origin"
+   ```
+5. **Clean up** - Clear stashes, prune remote branches
+6. **Verify** - All changes committed AND pushed
+7. **Hand off** - Provide context for next session
+
+**CRITICAL RULES:**
+- Work is NOT complete until `git push` succeeds
+- NEVER stop before pushing - that leaves work stranded locally
+- NEVER say "ready to push when you are" - YOU must push
+- If push fails, resolve and retry until it succeeds
+<!-- END BEADS INTEGRATION -->