raise-cli 2.2.1__py3-none-any.whl

raise_cli/skills_base/rai-welcome/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: rai-welcome
+description: >
+  Conversational developer onboarding for RaiSE. Detects scenario,
+  sets up profile and graph, offers optional personalization.
+
+license: MIT
+
+metadata:
+  raise.work_cycle: utility
+  raise.frequency: once-per-developer
+  raise.fase: "setup"
+  raise.prerequisites: ""
+  raise.next: "rai-session-start"
+  raise.gate: ""
+  raise.adaptable: "true"
+  raise.version: "2.0.0"
+  raise.visibility: public
+---
+
+# Welcome
+
+## Purpose
+
+Get a developer fully set up in a RaiSE project through a guided flow that detects their situation and only asks what's needed.
+
+## Mastery Levels (ShuHaRi)
+
+- **Shu**: Follow all steps, explain what each governance doc is for
+- **Ha**: Detect scenario and fast-path through known setups
+- **Ri**: One-shot setup with minimal questions
+
+## Context
+
+**When to use:** First time a developer works in a RaiSE project. Subsequent runs verify setup.
+
+**When to skip:** Developer is already set up (profile exists, graph exists, CLAUDE.local.md exists).
+
+**Inputs:** A project with `.raise/` directory (from `rai init`).
+
+## Steps
+
+### Step 1: Detect Scenario
+
+```bash
+ls ~/.rai/developer.yaml 2>/dev/null && echo "PROFILE_EXISTS" || echo "NO_PROFILE"
+ls .raise/ 2>/dev/null && echo "RAISE_EXISTS" || echo "NO_RAISE"
+```
+
+| Profile? | `.raise/`? | Action |
+|----------|------------|--------|
+| No | Yes | Full setup (Steps 2-5) |
+| Yes | Yes | Verify only (Step 4) |
+| Any | No | Stop: "Run `rai init` first, then `/rai-welcome` again." |
+
+<verification>
+Scenario detected. `.raise/` exists.
+</verification>
+
+### Step 2: Create Profile (if needed)
+
+Ask developer's name (only mandatory question). Derive pattern prefix (first letter, uppercased), confirm.
+
+```bash
+rai session start --name "{name}" --project .
+```
+
+Edit `~/.rai/developer.yaml` to add confirmed `pattern_prefix`.
+
+<verification>
+`~/.rai/developer.yaml` exists with name and pattern_prefix.
+</verification>
+
+### Step 3: Optional Personalization
+
+Frame as skippable: "Want to customize? Or skip — defaults work well."
+
+If customize, ask up to 3 questions:
+1. **Language:** English / Spanish / Other → `communication.language`
+2. **Style:** Detailed / Balanced / Direct → `communication.style`
+3. **Focus guidance:** Yes / No → `communication.redirect_when_dispersing`
+
+Defaults: `shu`, `balanced`, `en`, `detailed_explanations: true`, `redirect_when_dispersing: false`.
+
+<verification>
+Preferences saved or defaults accepted.
+</verification>
+
+### Step 4: Verify Setup
+
+Build graph if missing (`rai graph build`). Scaffold `CLAUDE.local.md` if missing. Run context bundle:
+
+```bash
+rai session start --project . --context
+```
+
+Check: developer name appears, session count shown, no errors.
+
+<verification>
+Profile, graph, and local config all present and functional.
+</verification>
+
+### Step 5: Welcome Message
+
+```
+Welcome to RaiSE, {name}!
+Setup: Profile ({prefix}), Graph ({N} concepts), CLAUDE.local.md
+Next: /rai-session-start
+```
+
+## Output
+
+| Item | Destination |
+|------|-------------|
+| Developer profile | `~/.rai/developer.yaml` |
+| Knowledge graph | `.raise/rai/memory/index.json` |
+| Local config | `CLAUDE.local.md` |
+| Next | `/rai-session-start` |
+
+## Quality Checklist
+
+- [ ] Scenario detected before asking any questions
+- [ ] Name is the only mandatory question
+- [ ] Personalization clearly framed as optional
+- [ ] Graph built if missing (not assumed)
+- [ ] Context bundle runs successfully after setup
+- [ ] NEVER overwrite existing CLAUDE.local.md
+- [ ] NEVER ask about experience level — learned implicitly through coaching
+
+## References
+
+- Profile model: `src/raise_cli/onboarding/profile.py`
+- Next: `/rai-session-start`
+- One-time skill: subsequent runs verify, not recreate

raise_cli/telemetry/__init__.py

@@ -0,0 +1,42 @@
+"""Telemetry module for local signal collection.
+
+This module provides infrastructure for collecting telemetry signals
+as specified in ADR-018 (Local Telemetry Architecture).
+
+Signals are stored locally in `.raise/rai/personal/telemetry/signals.jsonl` and follow
+OpenTelemetry semantic conventions for future OTLP export.
+"""
+
+from __future__ import annotations
+
+from raise_cli.telemetry.schemas import (
+    CalibrationEvent,
+    CommandUsage,
+    ErrorEvent,
+    SessionEvent,
+    Signal,
+    SkillEvent,
+    WorkLifecycle,
+)
+from raise_cli.telemetry.writer import (
+    EmitResult,
+    emit,
+    emit_command_usage,
+    emit_error_event,
+    emit_skill_event,
+)
+
+__all__ = [
+    "CalibrationEvent",
+    "CommandUsage",
+    "EmitResult",
+    "ErrorEvent",
+    "SessionEvent",
+    "Signal",
+    "SkillEvent",
+    "WorkLifecycle",
+    "emit",
+    "emit_command_usage",
+    "emit_error_event",
+    "emit_skill_event",
+]

raise_cli/telemetry/schemas.py

@@ -0,0 +1,285 @@
+"""Pydantic models for telemetry signals.
+
+This module defines the signal schemas for local telemetry collection
+as specified in ADR-018. Signals follow OpenTelemetry semantic conventions
+for future OTLP export compatibility.
+
+Signal types:
+- SkillEvent: Tracks skill invocations (start/complete/abandon)
+- SessionEvent: Tracks session outcomes
+- CalibrationEvent: Tracks estimate vs actual for velocity calibration
+- ErrorEvent: Tracks tool failures
+- CommandUsage: Tracks CLI command usage
+- WorkLifecycle: Tracks work items (epic/story) through phases (Lean flow analysis)
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, Field
+
+
+class SkillEvent(BaseModel):
+    """A skill invocation event.
+
+    Emitted when a skill starts, completes, or is abandoned.
+
+    Attributes:
+        type: Discriminator field, always "skill_event".
+        timestamp: When the event occurred (UTC).
+        skill: Name of the skill (e.g., "story-design").
+        event: Event type (start, complete, abandon).
+        duration_sec: Duration in seconds (only for complete/abandon).
+
+    Examples:
+        >>> from datetime import datetime, timezone
+        >>> event = SkillEvent(
+        ...     timestamp=datetime.now(timezone.utc),
+        ...     skill="story-design",
+        ...     event="complete",
+        ...     duration_sec=1800
+        ... )
+        >>> event.type
+        'skill_event'
+    """
+
+    type: Literal["skill_event"] = "skill_event"
+    timestamp: datetime = Field(..., description="When the event occurred (UTC)")
+    skill: str = Field(..., description="Name of the skill (e.g., 'story-design')")
+    event: Literal["start", "complete", "abandon"] = Field(
+        ..., description="Event type"
+    )
+    duration_sec: int | None = Field(
+        default=None, description="Duration in seconds (for complete/abandon)"
+    )
+
+
+class SessionEvent(BaseModel):
+    """A session lifecycle event.
+
+    Emitted when a session closes, capturing its outcome.
+
+    Attributes:
+        type: Discriminator field, always "session_event".
+        timestamp: When the event occurred (UTC).
+        session_type: Type of session (e.g., "story", "research").
+        outcome: How the session ended.
+        duration_min: Duration in minutes.
+        stories: Story IDs worked on during the session.
+
+    Examples:
+        >>> from datetime import datetime, timezone
+        >>> event = SessionEvent(
+        ...     timestamp=datetime.now(timezone.utc),
+        ...     session_type="story",
+        ...     outcome="success",
+        ...     duration_min=90,
+        ...     stories=["F9.1", "F9.2"]
+        ... )
+        >>> event.type
+        'session_event'
+    """
+
+    type: Literal["session_event"] = "session_event"
+    timestamp: datetime = Field(..., description="When the event occurred (UTC)")
+    session_type: str = Field(
+        ..., description="Type of session (e.g., 'story', 'research')"
+    )
+    outcome: Literal["success", "partial", "abandoned"] = Field(
+        ..., description="How the session ended"
+    )
+    duration_min: int = Field(..., description="Duration in minutes")
+    stories: list[str] = Field(default_factory=list, description="Story IDs worked on")
+
+
+class CalibrationEvent(BaseModel):
+    """A calibration data point for velocity tracking.
+
+    Emitted when a story is completed, comparing estimate to actual.
+
+    Attributes:
+        type: Discriminator field, always "calibration".
+        timestamp: When the event occurred (UTC).
+        story_id: Story identifier (e.g., "F9.1").
+        story_size: T-shirt size (XS, S, M, L).
+        estimated_min: Estimated duration in minutes.
+        actual_min: Actual duration in minutes.
+        velocity: Ratio of estimated to actual (>1 means faster than expected).
+
+    Examples:
+        >>> from datetime import datetime, timezone
+        >>> event = CalibrationEvent(
+        ...     timestamp=datetime.now(timezone.utc),
+        ...     story_id="F9.1",
+        ...     story_size="XS",
+        ...     estimated_min=25,
+        ...     actual_min=20,
+        ...     velocity=1.25
+        ... )
+        >>> event.velocity
+        1.25
+    """
+
+    type: Literal["calibration"] = "calibration"
+    timestamp: datetime = Field(..., description="When the event occurred (UTC)")
+    story_id: str = Field(..., description="Story identifier (e.g., 'F9.1')")
+    story_size: str = Field(..., description="T-shirt size (XS, S, M, L)")
+    estimated_min: int = Field(..., description="Estimated duration in minutes")
+    actual_min: int = Field(..., description="Actual duration in minutes")
+    velocity: float = Field(
+        ..., description="Ratio of estimated to actual (>1 = faster)"
+    )
+
+
+class ErrorEvent(BaseModel):
+    """A tool error event.
+
+    Emitted when a tool fails, for pattern detection.
+
+    Attributes:
+        type: Discriminator field, always "error_event".
+        timestamp: When the event occurred (UTC).
+        tool: Name of the tool that failed (e.g., "Bash", "Read").
+        error_type: Type of error (e.g., "command_not_found").
+        context: Brief context (no sensitive data).
+        recoverable: Whether the error was recoverable.
+
+    Examples:
+        >>> from datetime import datetime, timezone
+        >>> event = ErrorEvent(
+        ...     timestamp=datetime.now(timezone.utc),
+        ...     tool="Bash",
+        ...     error_type="command_not_found",
+        ...     context="pytest",
+        ...     recoverable=True
+        ... )
+        >>> event.recoverable
+        True
+    """
+
+    type: Literal["error_event"] = "error_event"
+    timestamp: datetime = Field(..., description="When the event occurred (UTC)")
+    tool: str = Field(..., description="Name of the tool that failed")
+    error_type: str = Field(..., description="Type of error")
+    context: str = Field(..., description="Brief context (no sensitive data)")
+    recoverable: bool = Field(..., description="Whether the error was recoverable")
+
+
+class CommandUsage(BaseModel):
+    """A CLI command usage event.
+
+    Emitted when a raise CLI command is invoked.
+
+    Attributes:
+        type: Discriminator field, always "command_usage".
+        timestamp: When the event occurred (UTC).
+        command: Main command name (e.g., "memory").
+        subcommand: Subcommand name if any (e.g., "query").
+
+    Examples:
+        >>> from datetime import datetime, timezone
+        >>> event = CommandUsage(
+        ...     timestamp=datetime.now(timezone.utc),
+        ...     command="memory",
+        ...     subcommand="query"
+        ... )
+        >>> event.command
+        'memory'
+    """
+
+    type: Literal["command_usage"] = "command_usage"
+    timestamp: datetime = Field(..., description="When the event occurred (UTC)")
+    command: str = Field(..., description="Main command name (e.g., 'memory')")
+    subcommand: str | None = Field(default=None, description="Subcommand name if any")
+
+
+class WorkLifecycle(BaseModel):
+    """A unified work lifecycle event for Lean flow analysis.
+
+    Tracks work items (epics, stories, etc.) through normalized phases to enable:
+    - Lead time calculation (start to complete)
+    - Wait time detection (gaps between phases)
+    - WIP tracking (started but not completed)
+    - Bottleneck identification (longest phase)
+    - Flow efficiency (active time / lead time)
+    - Cross-level analysis (compare epic vs story flow)
+
+    Phases (normalized across all work types):
+    - design: Scope definition and specification
+    - plan: Task/story decomposition and sequencing
+    - implement: Active development work
+    - review: Retrospective and learnings
+
+    Attributes:
+        type: Discriminator field, always "work_lifecycle".
+        timestamp: When the event occurred (UTC).
+        work_type: Type of work item (epic, story, etc.).
+        work_id: Work item identifier (e.g., "E9", "F9.4").
+        event: Lifecycle event type.
+        phase: Current phase in the workflow.
+        blocker: Description of blocker (only for blocked event).
+
+    Examples:
+        >>> from datetime import datetime, timezone
+        >>> event = WorkLifecycle(
+        ...     timestamp=datetime.now(timezone.utc),
+        ...     work_type="story",
+        ...     work_id="F9.4",
+        ...     event="start",
+        ...     phase="design"
+        ... )
+        >>> event.type
+        'work_lifecycle'
+
+        >>> epic = WorkLifecycle(
+        ...     timestamp=datetime.now(timezone.utc),
+        ...     work_type="epic",
+        ...     work_id="E9",
+        ...     event="complete",
+        ...     phase="review"
+        ... )
+        >>> epic.work_type
+        'epic'
+
+        >>> blocked = WorkLifecycle(
+        ...     timestamp=datetime.now(timezone.utc),
+        ...     work_type="story",
+        ...     work_id="F9.4",
+        ...     event="blocked",
+        ...     phase="plan",
+        ...     blocker="unclear requirements"
+        ... )
+        >>> blocked.blocker
+        'unclear requirements'
+    """
+
+    type: Literal["work_lifecycle"] = "work_lifecycle"
+    timestamp: datetime = Field(..., description="When the event occurred (UTC)")
+    work_type: Literal["epic", "story"] = Field(
+        ..., description="Type of work item (epic, story)"
+    )
+    work_id: str = Field(..., description="Work item identifier (e.g., 'E9', 'F9.4')")
+    event: Literal["start", "complete", "blocked", "unblocked", "abandoned"] = Field(
+        ..., description="Lifecycle event type"
+    )
+    phase: Literal["init", "design", "plan", "implement", "review", "close"] = Field(
+        ..., description="Current phase in the workflow"
+    )
+    blocker: str | None = Field(
+        default=None, description="Description of blocker (for blocked event)"
+    )
+
+
+# Union type for type-safe signal handling
+Signal = Annotated[
+    SkillEvent
+    | SessionEvent
+    | CalibrationEvent
+    | ErrorEvent
+    | CommandUsage
+    | WorkLifecycle,
+    Field(discriminator="type"),
+]
+"""Union of all signal types with discriminator for type-safe parsing."""

raise_cli/telemetry/writer.py

@@ -0,0 +1,217 @@
+"""Writer module for appending telemetry signals to JSONL.
+
+This module provides the `emit()` function to append signals to
+`.raise/rai/personal/telemetry/signals.jsonl` (gitignored, per-developer).
+
+Signals are written as JSON lines (one JSON object per line),
+which is append-friendly and git-friendly.
+
+Note: Telemetry is personal data (F14.15) and should not be committed.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import TYPE_CHECKING, Literal
+
+from raise_cli.compat import file_lock, file_unlock
+from raise_cli.config.paths import (
+    SIGNALS_FILE,
+    TELEMETRY_SUBDIR,
+    get_personal_dir,
+    get_session_dir,
+)
+
+if TYPE_CHECKING:
+    from raise_cli.telemetry.schemas import Signal
+
+# Type alias for skill event types (matches SkillEvent.event)
+SkillEventType = Literal["start", "complete", "abandon"]
+
+
+@dataclass
+class EmitResult:
+    """Result of emitting a signal.
+
+    Attributes:
+        success: Whether the signal was written successfully.
+        path: Path where the signal was written.
+        error: Error message if failed, None otherwise.
+    """
+
+    success: bool
+    path: Path | None = None
+    error: str | None = None
+
+
+def _get_telemetry_path(base_path: Path | None = None) -> Path:
+    """Get the path to the signals.jsonl file in personal directory.
+
+    Telemetry is personal data (per-developer, gitignored) per F14.15.
+    Path: .raise/rai/personal/telemetry/signals.jsonl
+
+    Args:
+        base_path: Project root directory. Defaults to current directory.
+
+    Returns:
+        Path to signals.jsonl file in personal directory.
+    """
+    return get_personal_dir(base_path) / TELEMETRY_SUBDIR / SIGNALS_FILE
+
+
+def _ensure_directory(path: Path) -> None:
+    """Ensure the parent directory exists.
+
+    Args:
+        path: Path to file whose parent directory should exist.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+
+def emit(
+    signal: Signal,
+    *,
+    base_path: Path | None = None,
+    session_id: str | None = None,
+) -> EmitResult:
+    """Emit a telemetry signal to the signals.jsonl file.
+
+    When session_id is provided, writes to per-session directory:
+        .raise/rai/personal/sessions/{session_id}/signals.jsonl
+
+    When session_id is None, writes to shared telemetry directory:
+        .raise/rai/personal/telemetry/signals.jsonl
+
+    Creates the directory if it doesn't exist. Uses file locking for
+    thread-safe writes. Telemetry is personal data (gitignored).
+
+    Args:
+        signal: The signal to emit (any of the 5 signal types).
+        base_path: Base directory for telemetry. Defaults to current directory.
+        session_id: Optional session ID for per-session isolation.
+
+    Returns:
+        EmitResult with success status and path or error message.
+    """
+    if session_id is not None:
+        path = get_session_dir(session_id, base_path) / SIGNALS_FILE
+    else:
+        path = _get_telemetry_path(base_path)
+
+    try:
+        _ensure_directory(path)
+
+        # Serialize signal to JSON line
+        json_line = signal.model_dump_json() + "\n"
+
+        # Append with file locking for thread safety
+        with open(path, "a", encoding="utf-8") as f:
+            file_lock(f)
+            try:
+                f.write(json_line)
+            finally:
+                file_unlock(f)
+
+        return EmitResult(success=True, path=path)
+
+    except PermissionError as e:
+        return EmitResult(
+            success=False, error=f"Permission denied writing to {path}: {e}"
+        )
+    except OSError as e:
+        return EmitResult(success=False, error=f"OS error writing to {path}: {e}")
+
+
+def emit_skill_event(
+    skill: str,
+    event: SkillEventType,
+    duration_sec: int | None = None,
+    *,
+    base_path: Path | None = None,
+    session_id: str | None = None,
+) -> EmitResult:
+    """Convenience function to emit a skill event.
+
+    Args:
+        skill: Name of the skill (e.g., "story-design").
+        event: Event type ("start", "complete", "abandon").
+        duration_sec: Duration in seconds (for complete/abandon).
+        base_path: Base directory for telemetry.
+        session_id: Optional session ID for per-session isolation.
+
+    Returns:
+        EmitResult with success status.
+    """
+    from raise_cli.telemetry.schemas import SkillEvent
+
+    signal = SkillEvent(
+        timestamp=datetime.now(UTC),
+        skill=skill,
+        event=event,
+        duration_sec=duration_sec,
+    )
+    return emit(signal, base_path=base_path, session_id=session_id)
+
+
+def emit_command_usage(
+    command: str,
+    subcommand: str | None = None,
+    *,
+    base_path: Path | None = None,
+    session_id: str | None = None,
+) -> EmitResult:
+    """Convenience function to emit a command usage event.
+
+    Args:
+        command: Main command name (e.g., "memory").
+        subcommand: Subcommand name if any (e.g., "query").
+        base_path: Base directory for telemetry.
+        session_id: Optional session ID for per-session isolation.
+
+    Returns:
+        EmitResult with success status.
+    """
+    from raise_cli.telemetry.schemas import CommandUsage
+
+    signal = CommandUsage(
+        timestamp=datetime.now(UTC),
+        command=command,
+        subcommand=subcommand,
+    )
+    return emit(signal, base_path=base_path, session_id=session_id)
+
+
+def emit_error_event(
+    tool: str,
+    error_type: str,
+    context: str,
+    recoverable: bool,
+    *,
+    base_path: Path | None = None,
+    session_id: str | None = None,
+) -> EmitResult:
+    """Convenience function to emit an error event.
+
+    Args:
+        tool: Name of the tool that failed (e.g., "Bash").
+        error_type: Type of error (e.g., "command_not_found").
+        context: Brief context (no sensitive data).
+        recoverable: Whether the error was recoverable.
+        base_path: Base directory for telemetry.
+        session_id: Optional session ID for per-session isolation.
+
+    Returns:
+        EmitResult with success status.
+    """
+    from raise_cli.telemetry.schemas import ErrorEvent
+
+    signal = ErrorEvent(
+        timestamp=datetime.now(UTC),
+        tool=tool,
+        error_type=error_type,
+        context=context,
+        recoverable=recoverable,
+    )
+    return emit(signal, base_path=base_path, session_id=session_id)