Merge branch 'latest-changes' into main after upstream sync and conflict resolution

Author: deepakdgupta1

.agent/rules/safety.md

@@ -0,0 +1,47 @@
+# Safety Rules for AI Coding Agents
+
+> These rules apply to all coding agents working on this project. They replicate the protection provided by DCG (Destructive Command Guard) for Claude Code.
+
+## Absolutely Forbidden Commands
+
+The following commands are **never** to be executed without explicit user approval in the same session:
+
+### Git Commands
+```bash
+git reset --hard           # Destroys uncommitted changes
+git checkout -- <files>    # Discards file changes permanently
+git restore <files>        # Same as checkout -- (not --staged)
+git push --force / -f      # Overwrites remote history
+git clean -f               # Deletes untracked files
+git branch -D              # Force-deletes without merge check
+git stash drop / clear     # Permanently deletes stashes
+```
+
+### Filesystem Commands
+```bash
+rm -rf <non-temp>          # Recursive deletion
+rmdir                      # Directory deletion
+```
+
+## Always Safe Commands
+```bash
+git checkout -b <branch>   # Creates branch, doesn't touch files
+git restore --staged       # Only unstages, safe
+git clean -n               # Dry-run, preview only
+rm -rf /tmp/...            # Temp directories are ephemeral
+git push --force-with-lease # Safe force push variant
+```
+
+## When You Need a Destructive Command
+
+1. **STOP** and explain to the user why it's needed
+2. **Suggest safer alternatives** if available
+3. **Ask the user to run it manually** if truly required
+4. **Never bypass** these protections—they exist for your safety too
+
+## Multi-Agent Awareness
+
+When working alongside other agents:
+- Never disturb changes you didn't make
+- Treat unfamiliar changes as if you made them yourself
+- Use MCP Agent Mail for file reservations when available

.agent/rules/ubs.md

@@ -0,0 +1,47 @@
+## UBS Quick Reference for AI Agents
+
+UBS stands for "Ultimate Bug Scanner": **The AI Coding Agent's Secret Weapon: Flagging Likely Bugs for Fixing Early On**
+
+**Install:** `curl -sSL https://raw.githubusercontent.com/Dicklesworthstone/ultimate_bug_scanner/master/install.sh | bash`
+
+**Golden Rule:** `ubs <changed-files>` before every commit. Exit 0 = safe. Exit >0 = fix & re-run.
+
+**Commands:**
+```bash
+ubs file.ts file2.py                    # Specific files (< 1s) — USE THIS
+ubs $(git diff --name-only --cached)    # Staged files — before commit
+ubs --only=js,python src/               # Language filter (3-5x faster)
+ubs --ci --fail-on-warning .            # CI mode — before PR
+ubs --help                              # Full command reference
+ubs sessions --entries 1                # Tail the latest install session log
+ubs .                                   # Whole project (ignores things like .venv and node_modules automatically)
+```
+
+**Output Format:**
+```
+⚠️  Category (N errors)
+    file.ts:42:5 – Issue description
+    💡 Suggested fix
+Exit code: 1
+```
+Parse: `file:line:col` → location | 💡 → how to fix | Exit 0/1 → pass/fail
+
+**Fix Workflow:**
+1. Read finding → category + fix suggestion
+2. Navigate `file:line:col` → view context
+3. Verify real issue (not false positive)
+4. Fix root cause (not symptom)
+5. Re-run `ubs <file>` → exit 0
+6. Commit
+
+**Speed Critical:** Scope to changed files. `ubs src/file.ts` (< 1s) vs `ubs .` (30s). Never full scan for small edits.
+
+**Bug Severity:**
+- **Critical** (always fix): Null safety, XSS/injection, async/await, memory leaks
+- **Important** (production): Type narrowing, division-by-zero, resource leaks
+- **Contextual** (judgment): TODO/FIXME, console logs
+
+**Anti-Patterns:**
+- ❌ Ignore findings → ✅ Investigate each
+- ❌ Full scan per edit → ✅ Scope to file
+- ❌ Fix symptom (`if (x) { x.y }`) → ✅ Root cause (`x?.y`)

.agent/skills/acfs-tools/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: acfs-tools
+description: ACFS CLI commands reference. Use when working with ACFS utilities like doctor, newproj, info, update, or dashboard.
+---
+
+# ACFS CLI Tools
+
+ACFS provides several CLI commands for managing your agentic coding environment.
+
+## Available Commands
+
+### `acfs doctor`
+
+Health check for installed tools. Run after installation or when troubleshooting.
+
+```bash
+acfs doctor              # Terminal output
+acfs doctor --json       # JSON output for scripting
+```
+
+### `acfs newproj`
+
+Create a new project with ACFS defaults (git init, AGENTS.md, beads, and multi-agent configs).
+
+```bash
+acfs newproj myapp                # CLI mode
+acfs newproj --interactive        # TUI wizard (recommended)
+acfs newproj -i myapp             # Prefill project name
+```
+
+### `acfs info`
+
+Lightning-fast system overview (reads cached state).
+
+```bash
+acfs info                # Terminal output
+acfs info --json         # JSON for scripting
+acfs info --minimal      # Just essentials
+```
+
+### `acfs update`
+
+Update all installed tools.
+
+```bash
+acfs-update              # Update apt, runtimes, shell, agents, cloud
+acfs-update --stack      # Include Dicklesworthstone stack
+acfs-update --dry-run    # Preview without changes
+```
+
+### `acfs cheatsheet`
+
+Discover aliases and shortcuts installed by ACFS.
+
+```bash
+acfs cheatsheet
+```
+
+### `acfs dashboard generate`
+
+Generate an HTML status page.
+
+```bash
+acfs dashboard generate
+```
+
+### `acfs services-setup`
+
+Configure agent credentials (Claude, Codex, Gemini, AMP).
+
+```bash
+acfs services-setup
+```
+
+### `acfs agent-resources`
+
+Manage shared agent resources in projects (status/diff/apply updates).
+
+```bash
+acfs agent-resources status /path/to/project
+acfs agent-resources diff /path/to/project
+acfs agent-resources apply /path/to/project
+```
+
+### `acfs continue`
+
+View upgrade progress after reboot (during Ubuntu upgrades).
+
+```bash
+acfs continue
+```
+
+## Key Aliases
+
+| Alias | Command | Notes |
+|-------|---------|-------|
+| `cc` | Claude Code | dangerously-skip-permissions |
+| `cod` | Codex CLI | dangerously-bypass-approvals |
+| `gmi` | Gemini CLI | yolo mode |
+| `amp` | Amp CLI | |
+
+## Configuration Files
+
+- `~/.acfs/state.json` — Installation state and checkpoints
+- `~/.acfs/zsh/acfs.zshrc` — Shell configuration
+- `~/.acfs/logs/` — Update and installation logs

.agent/skills/beads/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: beads
+description: Issue tracking with Beads (br/bv). Use when working with tasks, bugs, issues, or needing to triage work priorities.
+---
+
+# Issue Tracking with br (Beads)
+
+All issue tracking goes through **Beads**. No other TODO systems.
+
+**Note:** `br` is a convenience alias for the real Beads CLI: `bd`.
+
+## Key Invariants
+
+- `.beads/` is authoritative state and **must always be committed** with code changes.
+- Do not edit `.beads/*.jsonl` directly; only via `br` / `bd`.
+
+## Basic Commands
+
+```bash
+br ready --json                    # Check ready work
+br create "Title" -t bug -p 1      # Create issue (types: bug|feature|task|epic|chore)
+br update br-42 --status in_progress
+br close br-42 --reason "Done"
+br sync --flush-only               # Export without git ops
+```
+
+**Priorities:** `0` critical | `1` high | `2` medium | `3` low | `4` backlog
+
+## Agent Workflow
+
+1. `br ready` → find unblocked work
+2. `br update <id> --status in_progress` → claim
+3. Implement + test
+4. If new work found → `br create ... --deps discovered-from:<id>`
+5. `br close <id>` → complete
+6. Commit `.beads/` with code changes
+
+---
+
+# bv — Beads Viewer (AI Sidecar)
+
+Graph-aware triage engine with precomputed metrics (PageRank, betweenness, critical path).
+
+**⚠️ CRITICAL: Use ONLY `--robot-*` flags. Bare `bv` launches TUI that blocks your session.**
+
+## Core Commands
+
+```bash
+bv --robot-triage        # THE MEGA-COMMAND: start here
+bv --robot-next          # Single top pick + claim command
+bv --robot-plan          # Parallel execution tracks
+bv --robot-priority      # Priority misalignment detection
+```
+
+## Triage Output
+
+Returns: `quick_ref`, `recommendations`, `quick_wins`, `blockers_to_clear`, `project_health`, `commands`
+
+## Graph Analysis
+
+| Command | Returns |
+|---------|---------|
+| `--robot-insights` | PageRank, betweenness, HITS, cycles, critical path |
+| `--robot-label-health` | Per-label health levels |
+| `--robot-label-flow` | Cross-label dependencies |
+| `--robot-alerts` | Stale issues, blocking cascades |
+
+## Filtering
+
+```bash
+bv --robot-plan --label backend
+bv --recipe actionable --robot-triage
+bv --robot-triage --robot-triage-by-label
+```
+
+## jq Examples
+
+```bash
+bv --robot-triage | jq '.quick_ref'
+bv --robot-triage | jq '.recommendations[0]'
+bv --robot-insights | jq '.Cycles'
+```
+
+**Note:** Phase 1 (degree, topo sort) is instant. Phase 2 (PageRank, betweenness) has 500ms timeout.

.agent/skills/cass/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: cass
+description: Cross-agent session search. Use when looking for solutions from previous agent sessions or searching conversation history.
+---
+
+# cass — Cross-Agent Session Search
+
+`cass` indexes prior agent conversations (Claude Code, Codex, Cursor, Gemini, ChatGPT, etc.) so we can reuse solved problems.
+
+**Rule:** Never run bare `cass` (TUI). Always use `--robot` or `--json`.
+
+## Commands
+
+```bash
+cass health                                    # Check index status
+cass search "authentication error" --robot --limit 5
+cass view /path/to/session.jsonl -n 42 --json
+cass expand /path/to/session.jsonl -n 42 -C 3 --json
+cass capabilities --json
+cass robot-docs guide
+```
+
+## Tips
+
+- Use `--fields minimal` for lean output
+- Filter by agent with `--agent`
+- Use `--days N` to limit to recent history
+
+**stdout** is data-only, **stderr** is diagnostics; exit code 0 = success.
+
+Use cass to avoid re-solving problems other agents already handled.

.agent/skills/cm/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: cm
+description: Cass Memory System for agent learning. Use when retrieving past lessons, extracting rules from sessions, or building procedural memory.
+---
+
+# cass-memory (cm) — Agent Memory System
+
+The Cass Memory System gives agents procedural memory by analyzing historical sessions and extracting valuable lessons.
+
+## Quick Start
+
+```bash
+cm onboard status                              # Check status
+cm onboard sample --fill-gaps                  # Get sessions to analyze
+cm onboard read /path/to/session.jsonl --template
+cm playbook add "Rule content" --category "debugging"
+cm onboard mark-done /path/to/session.jsonl
+```
+
+## Before Complex Tasks
+
+```bash
+cm context "<task description>" --json
+```
+
+Returns:
+- **relevantBullets**: Rules that may help
+- **antiPatterns**: Pitfalls to avoid
+- **historySnippets**: Past sessions with similar problems
+- **suggestedCassQueries**: Searches for deeper investigation
+
+## Protocol
+
+1. **START**: `cm context "<task>" --json` before non-trivial work
+2. **WORK**: Reference rule IDs (e.g., "Following b-8f3a2c...")
+3. **FEEDBACK**: `// [cass: helpful b-xyz] - reason` or `// [cass: harmful b-xyz]`
+4. **END**: Just finish. Learning happens automatically.
+
+## Key Flags
+
+| Flag | Purpose |
+|------|---------|
+| `--json` | Machine-readable output (required!) |
+| `--limit N` | Cap rules returned |
+| `--no-history` | Faster response |

.agent/skills/csctf/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: csctf
+description: Convert AI chat share links to Markdown/HTML archives. Use when archiving AI conversations or building knowledge bases.
+---
+
+# csctf — Chat Shared Conversation to File
+
+Converts **AI chat share links** to Markdown/HTML.
+
+## Usage
+
+```bash
+csctf "https://chatgpt.com/share/..."       # ChatGPT
+csctf "https://gemini.google.com/share/..." # Gemini
+csctf "https://claude.ai/share/..."         # Claude
+csctf "..." --md-only                       # Markdown only
+csctf "..." --json                          # JSON metadata
+csctf "..." --publish-to-gh-pages --yes     # GitHub Pages
+```
+
+## Output
+
+- `<slug>.md` — Clean Markdown with code blocks
+- `<slug>.html` — Static HTML with syntax highlighting
+
+## Use Cases
+
+- Archive important AI conversations
+- Build searchable knowledge base
+- Share solutions with team
+- Document debugging sessions