raise-cli 2.2.1__py3-none-any.whl

raise_cli/skills/validator.py

@@ -0,0 +1,197 @@
+"""Validator for SKILL.md files.
+
+Validates skill structure against ADR-040 contract including:
+- Required fields (name, description, metadata)
+- Required sections (7 canonical: Purpose through References)
+- Line count target (≤150 body lines)
+- Naming conventions ({domain}-{action})
+- Hook paths (warns if script not found)
+"""
+
+from __future__ import annotations
+
+import re
+from enum import Enum
+from pathlib import Path
+
+from pydantic import BaseModel, Field, ValidationError
+
+from raise_cli.skills.parser import ParseError, parse_skill
+from raise_cli.skills.schema import Skill
+
+
+class ValidationSeverity(Enum):
+    """Severity level for validation issues."""
+
+    ERROR = "error"
+    WARNING = "warning"
+
+
+class ValidationResult(BaseModel):
+    """Result of validating a skill file."""
+
+    path: str = Field(description="Path to the validated file")
+    errors: list[str] = Field(
+        default_factory=lambda: [], description="Validation errors"
+    )
+    warnings: list[str] = Field(
+        default_factory=lambda: [], description="Validation warnings"
+    )
+
+    @property
+    def is_valid(self) -> bool:
+        """Skill is valid if there are no errors (warnings OK)."""
+        return len(self.errors) == 0
+
+    @property
+    def error_count(self) -> int:
+        """Number of errors."""
+        return len(self.errors)
+
+    @property
+    def warning_count(self) -> int:
+        """Number of warnings."""
+        return len(self.warnings)
+
+
+# ADR-040 canonical sections (7, fixed order)
+REQUIRED_SECTIONS = [
+    "Purpose",
+    "Mastery Levels",
+    "Context",
+    "Steps",
+    "Output",
+    "Quality Checklist",
+    "References",
+]
+
+# ADR-040 line count target for skill body
+MAX_BODY_LINES = 150
+
+# Pattern for {domain}-{action} naming convention
+NAMING_PATTERN = re.compile(r"^[a-z]+-[a-z]+(-[a-z]+)*$")
+
+
+def _validate_required_fields(skill: Skill, errors: list[str]) -> None:
+    """Check required frontmatter fields."""
+    if not skill.frontmatter.name:
+        errors.append("Missing required field: name")
+
+    if not skill.frontmatter.description:
+        errors.append("Missing required field: description")
+
+    if not skill.frontmatter.metadata:
+        errors.append("Missing required field: metadata")
+
+
+def _validate_required_sections(skill: Skill, errors: list[str]) -> None:
+    """Check required sections in body (ADR-040: 7 canonical sections)."""
+    body_lower = skill.body.lower()
+
+    for section in REQUIRED_SECTIONS:
+        # Match "## Section" with optional suffix (e.g., "## Mastery Levels (ShuHaRi)")
+        pattern = f"## {section.lower()}"
+        if pattern not in body_lower:
+            errors.append(f"Missing required section: {section}")
+
+
+def _validate_line_count(skill: Skill, warnings: list[str]) -> None:
+    """Warn if skill body exceeds ADR-040 line count target."""
+    body_lines = len(skill.body.strip().splitlines())
+    if body_lines > MAX_BODY_LINES:
+        warnings.append(f"Body has {body_lines} lines (target: ≤{MAX_BODY_LINES})")
+
+
+def _validate_naming_convention(skill: Skill, warnings: list[str]) -> None:
+    """Check naming follows {domain}-{action} pattern."""
+    name = skill.frontmatter.name
+    if name and not NAMING_PATTERN.match(name):
+        warnings.append(
+            f"Name '{name}' doesn't follow {{domain}}-{{action}} pattern (e.g., session-start)"
+        )
+
+
+def _validate_hook_paths(skill: Skill, warnings: list[str]) -> None:
+    """Check that hook script paths exist (warning only)."""
+    if not skill.frontmatter.hooks:
+        return
+
+    for hook_name, hook_list in skill.frontmatter.hooks.items():
+        for hook in hook_list:
+            for cmd in hook.hooks:
+                # Extract script path from command
+                # Handles: "RAISE_SKILL_NAME=x \"$CLAUDE_PROJECT_DIR\"/.raise/scripts/script.sh"
+                # Also handles: "/absolute/path/script.sh"
+                command = cmd.command
+
+                # Skip variable-based paths (we can't resolve them)
+                if "$" in command:
+                    continue
+
+                # Check if command looks like a path
+                if command.startswith("/"):
+                    path = Path(command.split()[0])  # Get first word (the path)
+                    if not path.exists():
+                        warnings.append(f"Hook '{hook_name}' script not found: {path}")
+
+
+def validate_skill(skill: Skill) -> ValidationResult:
+    """Validate a parsed Skill object.
+
+    Args:
+        skill: Parsed Skill object.
+
+    Returns:
+        ValidationResult with errors and warnings.
+    """
+    errors: list[str] = []
+    warnings: list[str] = []
+
+    _validate_required_fields(skill, errors)
+    _validate_required_sections(skill, errors)
+    _validate_line_count(skill, warnings)
+    _validate_naming_convention(skill, warnings)
+    _validate_hook_paths(skill, warnings)
+
+    return ValidationResult(
+        path=skill.path,
+        errors=errors,
+        warnings=warnings,
+    )
+
+
+def validate_skill_file(path: str | Path) -> ValidationResult:
+    """Validate a SKILL.md file.
+
+    Args:
+        path: Path to the SKILL.md file.
+
+    Returns:
+        ValidationResult with errors and warnings.
+    """
+    path = Path(path)
+    str_path = str(path)
+
+    # Check file exists
+    if not path.exists():
+        return ValidationResult(
+            path=str_path,
+            errors=[f"File not found: {path}"],
+        )
+
+    # Try to parse
+    try:
+        skill = parse_skill(path)
+    except ParseError as e:
+        return ValidationResult(
+            path=str_path,
+            errors=[f"Parse error: {e}"],
+        )
+    except ValidationError as e:
+        return ValidationResult(
+            path=str_path,
+            errors=[f"Schema error: {e}"],
+        )
+
+    # Validate the parsed skill
+    return validate_skill(skill)

raise_cli/skills_base/__init__.py

@@ -0,0 +1,80 @@
+"""Base skills package for distribution.
+
+This package contains the RaiSE skills that ship with raise-cli.
+On `rai init`, skill files are copied to the project's
+`.claude/skills/` directory (Claude Code) or equivalent IDE location.
+
+All skills use the `rai-` namespace prefix to prevent collision
+with user-created or third-party skills.
+
+Contents:
+    Session lifecycle:  rai-session-start, rai-session-close
+    Story lifecycle:    rai-story-start, rai-story-plan, rai-story-design,
+                        rai-story-implement, rai-story-review, rai-story-close
+    Epic lifecycle:     rai-epic-start, rai-epic-plan, rai-epic-design, rai-epic-close
+    Discovery:          rai-discover-start, rai-discover-scan,
+                        rai-discover-validate, rai-discover-document
+    Onboarding:         rai-project-create, rai-project-onboard, rai-welcome
+    Governance:         rai-docs-update
+    Quality:            rai-architecture-review, rai-quality-review
+    MCP:                rai-mcp-add, rai-mcp-remove, rai-mcp-status
+    Tools:              rai-research, rai-debug, rai-doctor, rai-problem-shape
+
+Note: Internal skills (rai-framework-sync, rai-publish, rai-skillset-manage,
+      rai-bugfix) are excluded from distribution.
+
+Usage:
+    from importlib.resources import files
+
+    base_skills = files("raise_cli.skills_base")
+    session_start = base_skills / "rai-session-start" / "SKILL.md"
+    content = session_start.read_text(encoding="utf-8")
+"""
+
+from __future__ import annotations
+
+__version__ = "2.2.0"
+
+DISTRIBUTABLE_SKILLS: list[str] = [
+    # Session lifecycle
+    "rai-session-close",
+    "rai-session-start",
+    # Story lifecycle
+    "rai-story-close",
+    "rai-story-design",
+    "rai-story-implement",
+    "rai-story-plan",
+    "rai-story-review",
+    "rai-story-run",
+    "rai-story-start",
+    # Epic lifecycle
+    "rai-epic-close",
+    "rai-epic-design",
+    "rai-epic-plan",
+    "rai-epic-run",
+    "rai-epic-start",
+    # Discovery
+    "rai-discover",
+    "rai-discover-document",
+    "rai-discover-scan",
+    "rai-discover-start",
+    "rai-discover-validate",
+    # Onboarding
+    "rai-project-create",
+    "rai-project-onboard",
+    "rai-welcome",
+    # Governance
+    "rai-docs-update",
+    # Quality
+    "rai-architecture-review",
+    "rai-quality-review",
+    # MCP
+    "rai-mcp-add",
+    "rai-mcp-remove",
+    "rai-mcp-status",
+    # Tools
+    "rai-debug",
+    "rai-doctor",
+    "rai-problem-shape",
+    "rai-research",
+]

raise_cli/skills_base/contract-template.md

@@ -0,0 +1,60 @@
+# Skill Contract Template (ADR-040)
+
+> Reference for refactoring skills to canonical structure.
+> Every SKILL.md follows exactly these 7 sections in this order.
+
+## Targets
+
+| Metric | Target |
+|--------|--------|
+| Sections | Exactly 7, fixed order |
+| Total lines | ≤150 (excluding YAML frontmatter) |
+| Discrete rules | ≤15 |
+| Substance ratio | ≥80% |
+| Examples | 1-2 per skill |
+| Negative phrases | ≤3 (reserve for true guardrails in Quality Checklist) |
+
+## Canonical Structure
+
+```markdown
+# {Skill Title}
+
+## Purpose
+One sentence: what this skill does and what success looks like.
+
+## Mastery Levels (ShuHaRi)
+≤5 lines. Behavior deltas SPECIFIC to this skill only.
+Universal ShuHaRi definitions are in the preamble — do not repeat them.
+
+## Context
+When to use / when to skip. Inputs required. Prerequisites (gates).
+Use decision tables for conditional logic, not prose paragraphs.
+
+## Steps
+### Step N: {Verb Phrase}
+Follow the step format convention from the preamble:
+- Action: what to do (affirmative phrasing)
+- Verification: how to check success
+- If blocked: recovery path
+
+Steps use clean integer numbering (1, 2, 3 — no 0.1, 1.5, 4b).
+
+## Output
+What this skill produces. Where artifacts go. State changes. Next skill.
+
+## Quality Checklist
+Atomic, verifiable items. This is the last thing the agent reads before
+finishing — recency bias means these get highest compliance.
+Place critical guardrails here (≤3 negative "NEVER" items if needed).
+
+## References
+Links only — no inline content. File paths, ADRs, related skills.
+```
+
+## Content Principles
+
+1. **Affirmative over negative** — "Do X when Y" instead of "Don't do X"
+2. **Decision tables over prose** — Branching logic as tables, not if-else paragraphs
+3. **Examples over rules** — One input/output example replaces 10+ lines of rules
+4. **Atomic instructions** — Each rule is one verifiable statement
+5. **Templates by reference** — Link to template files, don't inline them

raise_cli/skills_base/preamble.md

@@ -0,0 +1,37 @@
+# RaiSE Skill Preamble
+
+> Loaded once per session. Skills reference these conventions — they don't repeat them.
+
+## ShuHaRi — Developer Experience Level
+
+The developer's ShuHaRi level comes from their profile (`~/.rai/developer.yaml`). It reflects their experience with RaiSE, not general skill. Adapt your output verbosity — the process (steps) stays the same.
+
+| Level | Developer profile | Agent behavior |
+|-------|------------------|----------------|
+| **Shu** | New to RaiSE | Explain concepts, provide context, detailed step output |
+| **Ha** | Comfortable with RaiSE | Explain only what's new or non-obvious |
+| **Ri** | Veteran | Minimal output, essentials only, no explanations |
+
+## Step Format Convention
+
+Every step in a skill follows this structure:
+
+- **Action:** What to do (affirmative phrasing preferred)
+- **Verification:** How to confirm the step succeeded
+- **If blocked:** Recovery path when the step can't complete
+
+When blocked, stop and address the blocker. Do not skip steps or accumulate errors (Jidoka).
+
+## Graph Context Loading
+
+Skills that need codebase context use these CLI commands as early steps:
+
+```bash
+# Query patterns, decisions, guardrails
+rai graph query "<topic>" --types pattern,decision --limit 5
+
+# Load module architectural context
+rai graph context mod-<name>
+```
+
+If the graph is unavailable, run `rai graph build` first — or proceed without context if the work is self-contained.

raise_cli/skills_base/rai-architecture-review/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: rai-architecture-review
+description: >
+  Evaluate design proportionality and necessity using Beck's four rules.
+  Catches what correctness gates miss: over-engineering, orphaned abstractions,
+  speculative generality, and accumulated complexity. Parametrized for story
+  (local) and epic (systemic) scope.
+
+license: MIT
+
+metadata:
+  raise.work_cycle: story, epic
+  raise.frequency: on-demand
+  raise.prerequisites: story-implement (story scope), last story complete (epic scope)
+  raise.version: "1.0.0"
+  raise.visibility: internal
+---
+
+# Architecture Review
+
+## Purpose
+
+Evaluate whether code is **necessary and proportional** using Beck's four rules of simple design. Core question: "Could we achieve the same outcome with less?"
+
+## Mastery Levels (ShuHaRi)
+
+- **Shu**: Apply all heuristics systematically, explain each finding
+- **Ha**: Focus on highest-signal heuristics for the scope, skip low-risk areas
+- **Ri**: Pattern-match to known anti-patterns, minimal ceremony
+
+## Context
+
+| Condition | Action |
+|-----------|--------|
+| After `/rai-story-implement` | Run with `story` scope |
+| After last story in epic | Run with `epic` scope |
+| Accumulated complexity feels disproportionate | Run on-demand |
+
+**Inputs:** Scope (`story` or `epic`), design doc, changed files from git diff.
+
+## Steps
+
+### Step 1: Identify Scope and Changed Files
+
+Detect the project language and filter by appropriate extensions:
+
+1. **Check `.raise/manifest.yaml`** for `project.language` or `project.project_type`
+2. **Fallback:** Scan extensions of changed files and pick the dominant language
+
+```bash
+# Story scope: files changed vs parent branch
+git diff --name-only $(git merge-base HEAD <parent-branch>)..HEAD -- '<extensions>'
+# Epic scope: all files changed vs development branch
+git diff --name-only $(git merge-base HEAD <dev-branch>)..HEAD -- '<extensions>'
+```
+
+Replace `<extensions>` with language-appropriate patterns (e.g., `'*.py' '*.pyi'` for Python, `'*.ts' '*.tsx'` for TypeScript, `'*.cs'` for C#).
+
+Read every changed file and the design doc. You cannot judge proportionality without intent context.
+
+### Step 2: Necessity Audit (YAGNI — Beck Rule 4)
+
+| # | Heuristic | Red Flag |
+|---|-----------|----------|
+| H1 | Single Implementation | Protocol/ABC with exactly one concrete implementation, no documented consumer |
+| H2 | Wrapper Without Logic | Class delegates all work without adding behavior |
+| H3 | Unused Parameters | Parameters accepted but never used in function body |
+| H4 | Test-Only Consumers | Public function/class used exclusively by test code |
+| H5 | Dead Exports | Public API includes names no consumer imports (e.g., `__all__` in Python, `export` in TS, `public` in C#) |
+
+When a heuristic triggers, check: "Does the design doc justify this?" If yes, note as Observation.
+
+### Step 3: Proportionality Audit (KISS — Beck Rules 2+4)
+
+| # | Heuristic | Red Flag |
+|---|-----------|----------|
+| H6 | Indirection Depth | >2 layers of delegation for a simple operation |
+| H7 | Abstraction-to-LOC Ratio | More scaffolding than logic |
+| H8 | Configuration Over Convention | Configurable with only one valid value in practice |
+
+### Step 4: Duplication & Responsibility (Beck Rules 2-3)
+
+| # | Heuristic | Red Flag |
+|---|-----------|----------|
+| H9 | Semantic Duplication | Same concept expressed differently in multiple places |
+| H10 | Pattern Duplication | Same structural problem solved differently across modules |
+| H11 | Change Reason Count | Module changes for >1 unrelated reason |
+| H12 | Import Fan-In | File imports from 5+ distinct packages for one function |
+
+### Step 5: Systemic Audit (Epic Scope Only)
+
+Skip for story scope. Cross-module heuristics:
+
+| # | Heuristic | Red Flag |
+|---|-----------|----------|
+| H13 | Orphaned Abstractions | Protocol from early story still has ≤1 implementor at epic end |
+| H14 | Coupling Direction | Stable core imports from volatile/new module |
+| H15 | Cyclic Dependencies | Circular import paths between modules |
+| H16 | Shotgun Surgery | One logical change touches 5+ files across 3+ directories |
+
+### Step 6: Present Findings
+
+```markdown
+## Architecture Review: {id} (scope: {story|epic})
+
+### Critical (fix before merge)
+### Recommended (simplify before next cycle)
+### Questions (require human judgment)
+### Observations (patterns noted)
+### Verdict
+- [ ] PASS / PASS WITH QUESTIONS / SIMPLIFY
+```
+
+Every finding: specific file:line, heuristic ID, proportionality concern, concrete simplification.
+
+## Output
+
+| Item | Destination |
+|------|-------------|
+| Review findings | Presented inline, saved if requested |
+| Verdict | PASS, PASS WITH QUESTIONS, or SIMPLIFY |
+| Next | `/rai-story-review` (story) or `/rai-epic-close` (epic) |
+
+## Quality Checklist
+
+- [ ] Project language detected before filtering files
+- [ ] All changed files for detected language read before reviewing
+- [ ] Design doc loaded for intent context
+- [ ] Every finding cites specific file:line and heuristic ID (H1-H16)
+- [ ] Questions ratio >30% of findings (humility signal)
+- [ ] "No issues found" is a valid outcome — do not invent findings
+
+## References
+
+- Evidence: `work/research/architecture-review/`
+- Complements: `/rai-quality-review` (correctness), `/rai-story-review` (retrospective)
+- Framework: Beck's Simple Design Rules, Fowler's Code Smells, Silva et al. (ESEM 2024)

raise_cli/skills_base/rai-debug/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: rai-debug
+description: >
+  Systematic root cause analysis using lean methods (5 Whys, Ishikawa, Gemba).
+  Use when encountering unexpected behavior, errors, or defects to find and
+  fix the true root cause rather than symptoms.
+
+license: MIT
+
+metadata:
+  raise.work_cycle: utility
+  raise.frequency: as-needed
+  raise.fase: "0"
+  raise.prerequisites: ""
+  raise.next: story-plan
+  raise.gate: ""
+  raise.adaptable: "true"
+  raise.version: "2.1.0"
+  raise.visibility: public
+---
+
+# Debug
+
+## Purpose
+
+Systematically identify and fix the root cause of defects using lean methods. Stop fixing symptoms — find the true cause.
+
+## Mastery Levels (ShuHaRi)
+
+- **Shu**: Follow triage → method → fix strictly; document each step
+- **Ha**: Combine methods (Ishikawa + 5 Whys); adapt depth to complexity
+- **Ri**: Develop domain-specific diagnostic patterns; feed recurring patterns to graph
+
+## Context
+
+**When to use:** Unexpected behavior, unclear test failures, integration issues, performance problems, bug fix stories.
+
+**When to skip:** Obvious typos, simple syntax errors — go directly to fix.
+
+**Inputs:** Problem statement, steps to reproduce, error messages/symptoms. **Time boxing:** XS (5 min), S (15 min), M (30 min), L (60 min). Escalate if exceeded.
+
+## Steps
+
+### Step 0: Triage — Classify Complexity
+
+Before choosing a method, classify the bug:
+
+| Tier | Criteria | Method | Output |
+|------|----------|--------|--------|
+| **XS** | Cause evident, fix obvious | Skip to Step 3 | One-liner in scope/commit |
+| **S** | Cause obscure, single causal chain | 5 Whys (Step 2) | Summary block |
+| **M/L** | Multiple possible causes | Ishikawa (Step 2b) | `analysis.md` |
+
+State the tier explicitly before proceeding.
+
+<verification>
+Tier declared. Method selected.
+</verification>
+
+### Step 1: Define the Problem (Genchi Genbutsu)
+
+Go see the actual problem. Reproduce it, capture evidence:
+
+```
+WHAT:     [specific behavior observed]
+WHEN:     [conditions / triggers]
+WHERE:    [file:line or component]
+EXPECTED: [what should happen instead]
+```
+
+<verification>
+Problem is specific and reproducible (or minimal fixture built).
+</verification>
+
+<if-blocked>
+Cannot reproduce → gather logs, add instrumentation, build minimal fixture.
+</if-blocked>
+
+### Step 2: Root Cause Analysis (S bugs — 5 Whys)
+
+Ask "Why?" five times, staying on one factual causal chain:
+
+```
+Problem: [statement]
+1. Why? → [first-level cause, with evidence]
+2. Why? → [second-level cause]
+3. Why? → [third-level cause]
+4. Why? → [fourth-level cause]
+5. Why? → [root cause]
+Countermeasure: [fix]
+```
+
+Rules:
+- Each answer must be factual, not speculative
+- Stop when you reach something actionable and changeable
+- "Human error" is never a root cause — ask why the error was possible
+
+<verification>
+Root cause is actionable and explains all symptoms.
+</verification>
+
+<if-blocked>
+Chain branches → switch to Ishikawa (Step 2b).
+</if-blocked>
+
+### Step 2b: Ishikawa Diagram (M/L bugs — multiple causes)
+
+Explore 6 M's: Method, Machine, Material, Measurement, Manpower, Milieu (env/config drift).
+
+Identify top 2-3 hypotheses, investigate systematically:
+
+| Hypothesis | Test | Result | Conclusion |
+|------------|------|--------|------------|
+| [Cause 1]  | [How tested] | [What happened] | Confirmed/Eliminated |
+
+<verification>
+Root cause confirmed with evidence. Competing hypotheses eliminated.
+</verification>
+
+### Step 3: Fix & Prevent
+
+Fix the root cause (not symptoms). Write the regression test first (RED), then fix (GREEN).
+
+- [ ] Fix addresses confirmed root cause
+- [ ] Regression test written (RED → GREEN)
+- [ ] Original problem no longer reproduces
+- [ ] All existing tests pass
+
+Prevention (choose what applies):
+- Regression test (always for S+)
+- Input validation at boundary
+- Documentation or ADR update
+- `rai pattern add` for recurring systemic issues
+
+<verification>
+Problem resolved. Tests pass.
+</verification>
+
+<if-blocked>
+Fix incomplete → document partial fix, create follow-up task.
+</if-blocked>
+
+**Feed `/rai-story-plan`** — after fixing, name the tasks explicitly:
+- Fix task, regression test task, prevention task (if any)
+- Systemic finding: `rai pattern add "[statement]" --context "[keywords]" --type behavioral`
+
+## Output
+
+| Tier | Artifact | Destination |
+|------|----------|-------------|
+| XS | One-liner root cause + fix | Scope commit or inline |
+| S | Summary block (root cause, fix, prevention) | Story scope doc |
+| M/L | Full analysis | `work/debug/{issue-name}/analysis.md` |
+| Any | Story plan tasks | Fed to `/rai-story-plan` |
+
+## Quality Checklist
+
+- [ ] Tier declared before any analysis
+- [ ] Problem is specific and reproducible
+- [ ] Root cause identified with evidence (not speculation)
+- [ ] Fix addresses root cause, not symptoms
+- [ ] Regression test written (RED before GREEN)
+- [ ] Time box respected — escalate if exceeded
+- [ ] Story plan tasks named
+- [ ] NEVER guess — hypothesis first, then test. NEVER say "human error" — ask why the error was possible
+
+## References
+
+- 5 Whys: Taiichi Ohno, Toyota Production System
+- Ishikawa: Kaoru Ishikawa, "Guide to Quality Control"
+- Gemba: "Go and see" — Jidoka: stop on defects, fix immediately