anvil-dev-framework 0.1.8 → 0.1.9

package/README.md

@@ -1,7 +1,7 @@
 ```
      ___    _   ___     _____ _
     /   \  | \ | \ \   / /_ _| |
-   / /_\ \ |  \| |\ \ / / | || |      v0.1.8.0 (alpha)
+   / /_\ \ |  \| |\ \ / / | || |      v0.1.9.0 (alpha)
   / _____ \| |\  | \ V /  | || |___
  /_/     \_\_| \_|  \_/  |___|_____|
 
@@ -10,7 +10,7 @@
    ══════════════════════════════════════════════════════════
 ```
 
-# Anvil Development Framework <sup>v0.1.8.0</sup>
+# Anvil Development Framework <sup>v0.1.9.0</sup>
 
 > **A structured AI development system for solo builders who demand production-quality output.**
 
@@ -18,20 +18,21 @@ Anvil is a comprehensive framework for AI-assisted software development that com
 
 ---
 
-## 📦 Latest Changes in v0.1.8.0
+## 📦 Latest Changes in v0.1.9.0
 
-*Released: 2026-01-16*
+*Released: 2026-01-17*
 
+- **Ralph Visibility & Notification System** (ANV-298) — Real-time monitoring for autonomous execution
+  - Live terminal watcher (`ralph-watch`) with progress bars and event stream
+  - macOS Notification Center and TTS announcements for milestones
+  - Slack/Discord webhook integrations for team visibility
+  - REST API with SSE for future GUI integration
+  - Toggle notifications: `--enable/--disable {all,macos,tts,slack,discord}`
 - **Token Efficiency Audit Framework** — Complete token consumption tracking and optimization
   - `/efficiency` command for historical analysis with weekly/monthly reports
   - `/token-budget` command for session budget management with alerts
-  - Efficiency scoring (0-100), trend detection, and automated recommendations
 - **CodeRabbit Deep Integration** — Automated code review workflow
   - Enhanced `.coderabbit.yaml` with pre-merge checks and custom Anvil validations
-  - `/evidence` command integration with enforcement levels (soft/hard)
-- **Insights Watermark System** — Prevents re-analyzing processed retrospectives
-  - Manifest tracking in `.claude/insights/.manifest.json`
-  - `--all` flag to force re-analysis when needed
 
 See [CHANGELOG.md](CHANGELOG.md) for complete history.
 
@@ -157,16 +158,9 @@ npm install -g anvil-dev-framework
 anvil init
 ```
 
-**Option 3: Homebrew (macOS)** *(coming soon)*
+**Option 3: From Source**
 ```bash
-brew tap alexandercahiz/anvil
-brew install anvil
-anvil init
-```
-
-**Option 4: From Source**
-```bash
-git clone https://github.com/alexandercahiz/anvil-dev-framework.git
+git clone https://github.com/AMPMIO/anvil-dev-framework.git
 cd anvil-dev-framework
 ./scripts/install.sh  # Auto-configures PATH
 anvil init
@@ -541,6 +535,40 @@ This remains your **default approach** for all normal development work.
 
 **Recommendation**: Start with `--max-iterations 10` to understand costs before running overnight.
 
+### Monitoring Ralph Sessions
+
+Watch Ralph progress in real-time with the visibility tools:
+
+```bash
+# Terminal 1: Run Ralph
+/ralph start --issue ANV-209
+
+# Terminal 2: Watch progress (full display)
+python3 global/tools/ralph-watch
+
+# Or compact single-line mode
+python3 global/tools/ralph-watch --compact
+```
+
+**Notification Options:**
+```bash
+# Toggle notifications
+python3 global/lib/ralph_notifier.py --disable tts   # Mute TTS
+python3 global/lib/ralph_notifier.py --enable macos  # Enable desktop
+
+# Start API server for external monitoring
+python3 global/api/ralph_api.py --port 8765
+```
+
+**Event Types:**
+- `session_started` — Ralph begins work
+- `subtask_complete` — Linear subtask finished
+- `session_complete` — All work done
+- `error_occurred` — Something went wrong
+- `circuit_breaker` — No file changes detected (stuck)
+
+See `global/tools/README.md` for full documentation.
+
 ### Decision Flowchart
 
 ```
@@ -690,6 +718,7 @@ Anvil uses **four-part versioning**: `MILESTONE.MAJOR.MINOR.PATCH`
 ---
 
 ### Future (Post-1.0)
+- [ ] Homebrew CLI distribution (macOS/Linux)
 - [ ] Additional templates (mobile, Rails, Go)
 - [ ] VS Code extension
 - [ ] Dashboard for metrics
@@ -701,6 +730,7 @@ Anvil uses **four-part versioning**: `MILESTONE.MAJOR.MINOR.PATCH`
 
 | Document | Description |
 |----------|-------------|
+| [System Architecture](docs/system-architecture.md) | **OVERVIEW** — How Linear + CodeRabbit + Claude Code + Memory integrate |
 | [Session Workflow](docs/session-workflow.md) | **START HERE** — Daily coding workflow |
 | [Local Issue Tracking](docs/local-issues.md) | File-based issues without Linear |
 | [Sync Guide](docs/sync.md) | Keep projects updated with framework changes |

package/VERSION

@@ -1 +1 @@
-0.1.8.0
+0.1.9.0

package/docs/command-reference.md

@@ -22,6 +22,7 @@
 | `/discover` | File discovered work (bugs, debt) during implementation |
 | `/validate` | Environment validation before code changes |
 | `/evidence` | Capture quality gate proof before PR |
+| `/coderabbit-fix` | Apply CodeRabbit PR feedback automatically |
 | `/linear-setup` | Configure Linear integration for project |
 | `/anvil-sync` | Sync framework updates to project |
 | `/anvil-settings` | Manage framework settings |
@@ -70,6 +71,7 @@
 - [Quality Commands](#quality-commands)
   - [/validate](#validate)
   - [/evidence](#evidence)
+  - [/coderabbit-fix](#coderabbit-fix)
   - [/healthcheck](#healthcheck)
   - [/retro](#retro)
 - [Token Efficiency Commands](#token-efficiency-commands)
@@ -111,15 +113,9 @@ bun install -g anvil-dev-framework
 npm install -g anvil-dev-framework
 ```
 
-**Option 3: Homebrew (macOS)** *(coming soon)*
+**Option 3: From Source**
 ```bash
-brew tap alexandercahiz/anvil
-brew install anvil
-```
-
-**Option 4: From Source**
-```bash
-git clone https://github.com/alexandercahiz/anvil-dev-framework.git
+git clone https://github.com/AMPMIO/anvil-dev-framework.git
 cd anvil-dev-framework
 ./scripts/install.sh  # Auto-configures PATH
 ```
@@ -459,7 +455,7 @@ Anvil provides 23 slash commands organized into six categories:
 |----------|----------|---------|
 | **Session** | `/orient`, `/ready`, `/sprint`, `/handoff` | Session lifecycle management |
 | **Workflow** | `/explore`, `/spec`, `/plan`, `/tasks`, `/change`, `/discover` | Phase-gated development |
-| **Quality** | `/validate`, `/evidence`, `/healthcheck`, `/retro` | Quality assurance |
+| **Quality** | `/validate`, `/evidence`, `/coderabbit-fix`, `/healthcheck`, `/retro` | Quality assurance |
 | **Multi-Agent** | `/hud` | Multi-agent coordination |
 | **Maintenance** | `/release`, `/shard`, `/decay-review`, `/weekly-review`, `/insights` | System maintenance |
 | **Setup** | `/linear-setup`, `/anvil-sync`, `/anvil-settings` | Project configuration |
@@ -1207,7 +1203,7 @@ Or if failed:
 | Git Status | ✅ Required | Only expected files changed |
 | Documentation | ⚪ Soft | Prompts if docs may need updating |
 | Changelog | ⚪ Soft | Warns if no [Unreleased] entry |
-| Code Review | ⚪ Optional | Runs if enabled in config |
+| Code Review | ✅ Default | Runs automatically (enabled by default in v1.4+) |
 
 **Configuration** (`.claude/anvil.config.json`):
 
@@ -1216,16 +1212,21 @@ Or if failed:
   "codeReview": {
     "enabled": true,
     "tool": "coderabbit",
-    "command": "coderabbit --prompt-only",
-    "enforcement": "soft"
+    "command": "coderabbit review --plain",
+    "enforcement": "soft",
+    "preCommit": false,
+    "prePR": true,
+    "retryOnFix": true
   }
 }
 ```
 
-Code review enforcement levels:
-- **hard**: Run automatically, block PR if critical issues
-- **soft**: Prompt "Run code review? (recommended)"
-- **manual**: Skip automatic prompt, user triggers when wanted
+Code review configuration:
+- **enabled**: true by default (set to false to disable)
+- **enforcement**: `soft` (warn but allow) or `hard` (block on critical)
+- **preCommit**: run review before commits (default: false)
+- **prePR**: run review in /evidence (default: true)
+- **retryOnFix**: re-run review after fixes applied (default: true)
 
 **Output Format**:
 
@@ -1276,6 +1277,86 @@ Changes to be committed:
 
 ---
 
+### /coderabbit-fix
+
+**Purpose**: Apply CodeRabbit PR feedback automatically.
+
+**When to Use**: After CodeRabbit review identifies issues on your PR.
+
+**What It Does**:
+1. Fetches CodeRabbit comments from the current PR via GitHub CLI
+2. Parses suggestions, warnings, and errors
+3. Applies fixes bottom-up (preserves line numbers)
+4. Re-runs CodeRabbit review if `retryOnFix` enabled
+5. Commits changes with CodeRabbit co-author attribution
+
+**Prerequisites**:
+- PR must exist (created with `gh pr create`)
+- GitHub CLI (`gh`) installed and authenticated
+- CodeRabbit integration enabled on the repository
+
+**Arguments**:
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `--pr` | No | PR number (default: current branch's PR) |
+| `--dry-run` | No | Show what would be fixed without applying |
+
+**Configuration** (`.claude/anvil.config.json`):
+```json
+{
+  "codeReview": {
+    "enabled": true,
+    "tool": "coderabbit",
+    "command": "coderabbit review --plain",
+    "retryOnFix": true
+  }
+}
+```
+
+**Output Format**:
+
+```markdown
+## CodeRabbit Fix Report
+
+### PR: #123 (feature/password-reset)
+
+### Issues Found
+| Type | File | Line | Issue |
+|------|------|------|-------|
+| Error | src/auth.ts | 42 | Potential SQL injection |
+| Warning | src/utils.ts | 15 | Unused import |
+| Suggestion | src/api.ts | 88 | Consider error handling |
+
+### Fixes Applied
+- ✅ src/auth.ts:42 — Parameterized query
+- ✅ src/utils.ts:15 — Removed unused import
+- ⚠️ src/api.ts:88 — Manual review required
+
+### Summary
+- **Auto-fixed**: 2 issues
+- **Manual review**: 1 issue
+- **Re-review**: Running...
+
+### Next Steps
+1. Review manual items marked ⚠️
+2. Commit with: `git commit -m "fix: address CodeRabbit feedback"`
+```
+
+**Integration with /evidence**:
+
+When CodeRabbit finds issues during `/evidence`:
+```
+⚠️ CodeRabbit found 3 issues.
+Run `/coderabbit-fix` to apply suggested fixes automatically.
+```
+
+**Related Commands**:
+- `/evidence` — Runs CodeRabbit review as part of quality gates
+- `/weekly-review` — Analyzes CodeRabbit patterns over time
+
+---
+
 ### /healthcheck
 
 **Purpose**: Framework diagnostics and session health analysis.

package/docs/system-architecture.md

@@ -201,6 +201,21 @@ CodeRabbit is the **automated code reviewer** that catches issues before humans
 - Custom pre-merge check rules
 - Automated response to review comments
 
+**Anvil Config (`.claude/anvil.config.json`):**
+```json
+{
+  "codeReview": {
+    "enabled": true,
+    "tool": "coderabbit",
+    "command": "coderabbit review --plain",
+    "enforcement": "soft",    // soft = warn, hard = block
+    "preCommit": false,
+    "prePR": true,            // run in /evidence
+    "retryOnFix": true        // re-run after fixes
+  }
+}
+```
+
 ---
 
 ### 3. Claude Code + Anvil Layer

package/global/api/openapi.yaml

@@ -0,0 +1,357 @@
+openapi: 3.0.3
+info:
+  title: Ralph API
+  description: |
+    REST and SSE API for monitoring Ralph autonomous execution sessions.
+
+    Provides real-time access to session status, event history, and control commands.
+  version: 1.0.0
+  contact:
+    name: Anvil Framework
+  license:
+    name: MIT
+
+servers:
+  - url: http://localhost:8765
+    description: Local development server
+
+tags:
+  - name: Health
+    description: Health check endpoints
+  - name: Session
+    description: Current session information
+  - name: Events
+    description: Event history and streaming
+  - name: Control
+    description: Session control commands
+
+paths:
+  /health:
+    get:
+      tags: [Health]
+      summary: Health check
+      description: Returns server health status and connection info
+      operationId: getHealth
+      responses:
+        '200':
+          description: Server is healthy
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/HealthResponse'
+
+  /status:
+    get:
+      tags: [Session]
+      summary: Get current session status
+      description: Returns detailed status of the current Ralph session
+      operationId: getStatus
+      security:
+        - ApiKeyAuth: []
+      responses:
+        '200':
+          description: Session status
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/StatusResponse'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+
+  /events:
+    get:
+      tags: [Events]
+      summary: SSE event stream
+      description: |
+        Server-Sent Events stream for real-time event updates.
+
+        Events:
+        - `status`: Connection status
+        - `event`: Ralph event (subtask_complete, error, etc.)
+        - `heartbeat`: Keep-alive ping
+      operationId: getEvents
+      security:
+        - ApiKeyAuth: []
+      responses:
+        '200':
+          description: SSE stream established
+          content:
+            text/event-stream:
+              schema:
+                type: string
+                example: |
+                  event: status
+                  data: {"state": "connected", "ralph_active": true}
+
+                  event: event
+                  data: {"event_type": "subtask_complete", ...}
+
+                  event: heartbeat
+                  data: {"time": 1234567890.123}
+
+  /history:
+    get:
+      tags: [Events]
+      summary: Get event history
+      description: Returns recent events from the current session
+      operationId: getHistory
+      security:
+        - ApiKeyAuth: []
+      parameters:
+        - name: limit
+          in: query
+          description: Maximum number of events to return
+          schema:
+            type: integer
+            default: 50
+            minimum: 1
+            maximum: 500
+      responses:
+        '200':
+          description: Event history
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/HistoryResponse'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+
+  /sessions:
+    get:
+      tags: [Session]
+      summary: Get past session summaries
+      description: Returns summaries of previous Ralph sessions
+      operationId: getSessions
+      security:
+        - ApiKeyAuth: []
+      responses:
+        '200':
+          description: Session summaries
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SessionsResponse'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+
+  /control:
+    post:
+      tags: [Control]
+      summary: Send control command
+      description: Send a control command to the Ralph session (e.g., stop)
+      operationId: postControl
+      security:
+        - ApiKeyAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ControlRequest'
+      responses:
+        '200':
+          description: Command executed
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ControlResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          description: No active session
+
+components:
+  securitySchemes:
+    ApiKeyAuth:
+      type: apiKey
+      in: header
+      name: X-API-Key
+      description: Optional API key for authentication
+
+  schemas:
+    HealthResponse:
+      type: object
+      properties:
+        status:
+          type: string
+          example: healthy
+        ralph_active:
+          type: boolean
+          example: true
+        sse_clients:
+          type: integer
+          example: 2
+        timestamp:
+          type: string
+          format: date-time
+
+    StatusResponse:
+      type: object
+      properties:
+        active:
+          type: boolean
+        iteration:
+          type: integer
+          example: 5
+        status:
+          type: string
+          enum: [running, completed, circuit_breaker, fatal_error, stopped]
+        task_name:
+          type: string
+          example: "Migration Task"
+        started_at:
+          type: string
+          format: date-time
+        progress:
+          $ref: '#/components/schemas/Progress'
+        no_change_count:
+          type: integer
+        checkpoint_active:
+          type: boolean
+        linear_subtasks:
+          type: array
+          items:
+            $ref: '#/components/schemas/LinearSubtask'
+
+    Progress:
+      type: object
+      properties:
+        completed:
+          type: integer
+        total:
+          type: integer
+        percent:
+          type: number
+          format: float
+
+    LinearSubtask:
+      type: object
+      properties:
+        identifier:
+          type: string
+          example: ANV-123
+        title:
+          type: string
+        status:
+          type: string
+          enum: [todo, in_progress, completed]
+
+    RalphEvent:
+      type: object
+      properties:
+        event_id:
+          type: string
+          format: uuid
+        event_type:
+          type: string
+          enum:
+            - session_started
+            - iteration_complete
+            - subtask_complete
+            - session_complete
+            - error_occurred
+            - circuit_breaker
+            - checkpoint_triggered
+        timestamp:
+          type: string
+          format: date-time
+        session_id:
+          type: string
+        task_name:
+          type: string
+        iteration:
+          type: integer
+        progress:
+          $ref: '#/components/schemas/Progress'
+        payload:
+          type: object
+          additionalProperties: true
+        linear:
+          type: object
+          properties:
+            parent_issue:
+              type: string
+            subtask:
+              type: string
+            url:
+              type: string
+              format: uri
+
+    HistoryResponse:
+      type: object
+      properties:
+        count:
+          type: integer
+        events:
+          type: array
+          items:
+            $ref: '#/components/schemas/RalphEvent'
+
+    SessionSummary:
+      type: object
+      properties:
+        file:
+          type: string
+        session_id:
+          type: string
+        task_name:
+          type: string
+        started_at:
+          type: string
+          format: date-time
+        ended_at:
+          type: string
+          format: date-time
+        event_count:
+          type: integer
+        final_status:
+          type: string
+
+    SessionsResponse:
+      type: object
+      properties:
+        count:
+          type: integer
+        sessions:
+          type: array
+          items:
+            $ref: '#/components/schemas/SessionSummary'
+
+    ControlRequest:
+      type: object
+      required:
+        - command
+      properties:
+        command:
+          type: string
+          enum: [stop]
+
+    ControlResponse:
+      type: object
+      properties:
+        success:
+          type: boolean
+        message:
+          type: string
+
+    Error:
+      type: object
+      properties:
+        error:
+          type: string
+
+  responses:
+    BadRequest:
+      description: Bad request
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+    Unauthorized:
+      description: Unauthorized - invalid or missing API key
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'