raise-cli 2.2.1__py3-none-any.whl

raise_cli/skills_base/rai-session-close/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: rai-session-close
+description: >
+  Close a working session by reflecting on outcomes and feeding structured data to CLI.
+  CLI does all writes atomically; skill does inference reflection.
+
+license: MIT
+
+metadata:
+  raise.work_cycle: session
+  raise.frequency: per-session
+  raise.fase: "end"
+  raise.prerequisites: ""
+  raise.next: ""
+  raise.gate: ""
+  raise.adaptable: "true"
+  raise.version: "4.1.0"
+  raise.visibility: public
+  raise.inputs: |
+    - session_id: string, required, previous_skill
+  raise.outputs: |
+    - session_record: file_path, file
+    - patterns: list, cli
+---
+
+# Session Close
+
+## Purpose
+
+Close a session by reflecting on outcomes and feeding structured data to the CLI for atomic persistence.
+
+## Mastery Levels (ShuHaRi)
+
+- **Shu**: Detailed handoff with explanations of what was captured
+- **Ha**: Standard handoff, explain only notable items
+- **Ri**: Minimal handoff — next step and open items only
+
+## Context
+
+**When to use:** At the end of every working session.
+
+**Quick close:** For short sessions, use CLI flags directly instead of a state file:
+```bash
+rai session close --summary "Quick fix session" --type maintenance --project .
+```
+
+## Steps
+
+### Step 1: Craft Session Title
+
+Generate a descriptive session title (max 80 chars) that captures what was accomplished — not planned, accomplished. Include the **epic/story name** (not just the number) so the title is self-explanatory without looking up Jira. Use the format: `SES-{ID}: {title}`.
+
+**Good** (descriptive, includes context):
+- `SES-321: E355 Branch Model Evolution cerrado + backlog review y priorización E354`
+- `SES-318: E347 Backlog Automation — epic completo, 7 stories, merge a dev`
+- `SES-316: Backlog sync + Semgrep MCP investigation`
+
+**Bad** (too terse, requires lookup):
+- `SES-321: E355 complete + backlog review`
+- `SES-318: E347 done`
+
+The title will be used in the `summary` field of the state file AND presented to the human for `/rename`.
+
+### Step 2: Reflect & Produce State File
+
+Use inference to reflect on the session and write a YAML state file:
+
+```yaml
+# .raise/rai/personal/session-output.yaml
+session_id: "{SES-ID}"
+summary: "{session_title}"  # The concise title from Step 1
+type: feature  # feature | research | maintenance | infrastructure | ideation
+outcomes:
+  - "Concrete deliverable 1"
+patterns:
+  - description: "Pattern learned"
+    context: "tag1,tag2"
+    type: process
+corrections:
+  - what: "Behavioral observation"
+    lesson: "Lesson learned"
+coaching:                          # Only include fields that changed
+  trust_level: "established"
+  strengths: ["structured thinking"]
+  growth_edge: "async patterns"
+  autonomy: "high within defined scope"
+  relationship:
+    quality: "productive"
+    trajectory: "stable"
+current_work:
+  release: V3.0
+  epic: E15
+  story: S15.7
+  phase: implement
+  branch: story/s15.7/session-protocol
+pending:
+  decisions: []
+  blockers: []
+  next_actions: ["Continue with Task 7"]
+narrative: |
+  ## Decisions
+  - Key decisions and WHY
+  ## Research
+  - Conclusions with file paths
+  ## Artifacts
+  - Files created/modified
+  ## Branch State
+  - Branch and commits ahead of base
+next_session_prompt: |
+  Forward-looking guidance to future Rai. What to prioritize,
+  what to watch for, what context will be critical.
+```
+
+**Capture tangents:** Check conversation for ideas → add to `dev/parking-lot.md`.
+
+### Step 3: Clean Working Tree
+
+Before closing, ensure no uncommitted changes are left behind:
+
+1. Run `git status`
+2. If working tree is clean → proceed to Step 3
+3. If there are uncommitted changes → present them to the human with options:
+   - **Commit**: stage and commit with a descriptive message
+   - **Discard**: `git restore` the files (confirm first)
+   - **Leave**: explicitly acknowledge the leftovers in the handoff
+4. Do NOT close the session with a dirty working tree unless the human explicitly chooses "Leave"
+
+### Step 4: Feed CLI
+
+```bash
+rai session close --state-file .raise/rai/personal/session-output.yaml --session {SES-ID} --project .
+```
+
+This atomically: records session in index, appends patterns, updates coaching, writes session state, clears active session.
+
+Present the closing card:
+
+```
+## Session Closed: SES-{ID} {session_title}
+
+**Type:** {type}
+**Outcomes:**
+- {outcome 1}
+- {outcome 2}
+**Patterns:** {N new} | **Working tree:** {clean | N files uncommitted}
+
+### Next Session
+**Continue:** [next step]
+**Open:** [unresolved questions, if any]
+```
+
+## Output
+
+| File | Update | Writer |
+|------|--------|--------|
+| `.raise/rai/personal/sessions/index.jsonl` | Session record | CLI |
+| `.raise/rai/memory/patterns.jsonl` | New patterns | CLI |
+| `~/.rai/developer.yaml` | Coaching + clear session | CLI |
+| `.raise/rai/session-state.yaml` | Working state | CLI |
+| `dev/parking-lot.md` | Tangents | Skill (Edit) |
+
+## Quality Checklist
+
+- [ ] Session ID matches the active session from session-start
+- [ ] Summary reflects actual outcomes (not planned intent)
+- [ ] Narrative enables next session to resume immediately
+- [ ] Next session prompt is actionable and specific
+- [ ] Tangents captured in parking lot (if any)
+- [ ] Working tree clean (or leftovers explicitly acknowledged)
+- [ ] CLI close command executed successfully
+
+## References
+
+- Complement: `/rai-session-start`
+- Session state: `.raise/rai/session-state.yaml`
+- Parking lot: `dev/parking-lot.md`

raise_cli/skills_base/rai-session-start/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: rai-session-start
+description: >
+  Begin a session by loading context bundle, interpreting it, and proposing work.
+  CLI does all data plumbing; skill does inference interpretation.
+
+license: MIT
+
+metadata:
+  raise.work_cycle: session
+  raise.frequency: per-session
+  raise.fase: "start"
+  raise.prerequisites: ""
+  raise.next: ""
+  raise.gate: ""
+  raise.adaptable: "true"
+  raise.version: "5.0.0"
+  raise.visibility: public
+  raise.inputs: |
+    - project_path: string, required, argument
+    - developer_profile: file_path, required, config
+  raise.outputs: |
+    - session_id: string, next_skill
+    - context_bundle: string, cli
+---
+
+# Session Start
+
+## Purpose
+
+Load context bundle from CLI, interpret signals, and propose focused work for the session.
+
+## Mastery Levels (ShuHaRi)
+
+- **Shu**: Explain context, progress metrics, and concepts in presentation
+- **Ha**: Explain only new or non-obvious signals
+- **Ri**: Minimal output — context line, focus, signals, "Go."
+
+## Context
+
+**When to use:** At the start of every working session.
+
+**When to skip:** Continuation of an active session (context already loaded).
+
+**Inputs:** Developer profile (`~/.rai/developer.yaml`). If no profile exists, ask for the developer's name and pass `--name "Name"`.
+
+## Steps
+
+### Step 1: Load Orientation Bundle
+
+```bash
+rai session start --project . --context
+```
+
+Loads developer profile, session state, and orientation bundle. If graph unavailable: run `rai graph build` first.
+
+**IMPORTANT:** This is the ONLY CLI command in this skill. The context bundle output is complete — do NOT invent additional flags (e.g. `--section`), sub-commands (e.g. `rai context load`), or follow-up CLI calls to "fetch more". If the bundle mentions available context sections, that information is for display only. All interpretation happens in Step 2 using inference, not additional tool calls.
+
+### Step 2: Interpret & Present
+
+1. **Check signals** (priority order):
+   - Next session prompt → guidance from your past self, highest-priority continuity
+   - Release/deadline pressure → flag urgency with days remaining
+   - Session narrative → review decisions, research, artifacts for continuity
+   - Pending decisions or blockers → address first
+   - Communication preferences → adapt tone
+
+2. **Check MCP health** (non-blocking):
+   - Run `rai mcp list` to detect registered servers
+   - If no servers registered: skip silently (no output)
+   - If servers found: run `rai mcp health <name>` for each
+   - Collect status: healthy count, unhealthy count, total
+
+3. **Propose session focus** from: pending items > current story/phase > deadlines
+
+4. **Present** (adapt verbosity to developer level):
+
+```
+## Session: YYYY-MM-DD
+
+**Context:** [Release →] [Epic] → [Story], [phase]
+**Focus:** [goal]
+**MCP:** [{total} servers, all healthy] or [{total} servers, {unhealthy} unhealthy — run /rai-mcp-status]
+**Signals:** [any, or "None"]
+```
+
+Omit the **MCP:** line entirely if no servers are registered.
+
+## Output
+
+| Item | Destination |
+|------|-------------|
+| Session initialized | CLI session state updated |
+| Focus proposed | Presented to developer |
+| Next | Begin work on proposed focus |
+
+## Quality Checklist
+
+- [ ] Orientation bundle loaded successfully
+- [ ] Signals interpreted in priority order
+- [ ] Session focus proposed from pending work
+- [ ] Verbosity adapted to developer ShuHaRi level
+- [ ] MCP health checked when servers registered (silent skip if none)
+
+## References
+
+- Profile: `~/.rai/developer.yaml`
+- Session state: `.raise/rai/session-state.yaml`
+- MCP: `rai mcp list`, `rai mcp health`, `/rai-mcp-status`
+- Complement: `/rai-session-close`

raise_cli/skills_base/rai-story-close/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: rai-story-close
+description: >
+  Complete a story with retrospective verification, merge to dev,
+  cleanup, and tracking update. Use after review to formally close
+  the story lifecycle.
+
+license: MIT
+
+metadata:
+  raise.work_cycle: story
+  raise.frequency: per-story
+  raise.fase: "8"
+  raise.prerequisites: story-review
+  raise.next: ""
+  raise.gate: ""
+  raise.adaptable: "true"
+  raise.version: "3.0.0"
+  raise.visibility: public
+  raise.inputs: |
+    - retrospective_md: file_path, required, previous_skill
+    - tests_passing: boolean, required, cli
+    - dev_branch: string, required, config
+  raise.outputs: |
+    - merge_commit: string, git
+---
+
+# Story Close
+
+## Purpose
+
+Complete a story by verifying the retrospective, merging to the development branch, cleaning up the story branch, and updating epic tracking.
+
+## Mastery Levels (ShuHaRi)
+
+- **Shu**: Follow all steps, verify retrospective, merge with --no-ff, update epic
+- **Ha**: Adjust merge strategy for small fixes, skip epic update for standalone
+- **Ri**: Integrate with CI/CD pipelines, automate cleanup workflows
+
+## Context
+
+**When to use:** After `/rai-story-review` retrospective is complete. Story is verified and tests pass.
+
+**When to skip:** Story abandoned (document why, delete branch without merge, update epic as "Abandoned").
+
+**Inputs:** Completed retrospective, passing test suite, story branch ready for merge.
+
+**Branch config:** Read `branches.development` from `.raise/manifest.yaml` for `{dev_branch}`. Default: `main`.
+
+## Steps
+
+### Step 1: Verify Retrospective & Tests
+
+```bash
+RETRO="work/epics/e{N}-{name}/stories/{story_id}-retrospective.md"
+[ -f "$RETRO" ] && echo "✓ Retrospective" || echo "ERROR: Run /rai-story-review first"
+```
+
+Determine which test command to run using this priority chain:
+
+1. **Check `.raise/manifest.yaml`** for `project.test_command` — if set, use it directly (configuration over convention)
+2. **Detect language** from `project.project_type` in manifest, or scan file extensions of changed files (`git diff --name-only`)
+3. **Map language to default** using the table below
+
+| Language | Extensions | Default Test Command |
+|----------|-----------|----------------------|
+| Python | `.py`, `.pyi` | `uv run pytest --tb=short` |
+| TypeScript | `.ts`, `.tsx` | `npx vitest run` or `npm test` |
+| JavaScript | `.js`, `.jsx` | `npx vitest run` or `npm test` |
+| C# | `.cs` | `dotnet test --verbosity quiet` |
+| Go | `.go` | `go test ./...` |
+| PHP | `.php` | `vendor/bin/phpunit` |
+| Dart | `.dart` | `flutter test` |
+| Unknown | — | Ask developer |
+
+The table is a **fallback** — `project.test_command` always wins when present.
+
+| Condition | Action |
+|-----------|--------|
+| Retro exists + tests green | Continue |
+| Retro missing | Run `/rai-story-review` first — no exceptions |
+| Tests failing | Fix before merge |
+
+Check for structural drift: if this story added modules or changed directory structure, update module docs in `governance/architecture/modules/` before closing.
+
+<verification>
+Retrospective exists. Tests pass. No undocumented structural changes.
+</verification>
+
+### Step 2: Verify Clean Working Tree
+
+```bash
+git status --short
+```
+
+| Condition | Action |
+|-----------|--------|
+| Working tree clean | Continue to merge |
+| Uncommitted changes from this story | **Commit them** before merge — artifacts must not be orphaned |
+| Unrelated changes | Stash or commit separately with `chore:` prefix |
+
+**NEVER merge with uncommitted story artifacts.** Files created during design, plan, or implementation that aren't committed will be silently lost or orphaned on the target branch.
+
+<verification>
+`git status` shows clean working tree (or only unrelated files explicitly acknowledged).
+</verification>
+
+### Step 3: Merge to Development Branch
+
+Always merge to `{dev_branch}`:
+
+```bash
+git checkout {dev_branch}
+git pull origin {dev_branch}
+git merge --no-ff {story_branch} -m "feat(s{N}.{M}): merge {story-name}
+
+Completed:
+- [summary of deliverables]
+
+Co-Authored-By: Rai <rai@humansys.ai>"
+```
+
+<verification>
+Merge commit created on `{dev_branch}`.
+</verification>
+
+<if-blocked>
+Merge conflicts → resolve preserving story work.
+</if-blocked>
+
+### Step 4: Update Epic Scope
+
+Mark story complete in `work/epics/e{N}-{name}/scope.md`:
+- Check the story checkbox: `- [x] S{N}.{M} {name} ✓`
+- Update progress tracking table (status, actual time, velocity)
+
+<verification>
+Epic scope reflects story completion.
+</verification>
+
+### Step 5: Delete Story Branch
+
+```bash
+git branch -D story/s{N}.{M}/{slug}
+git push origin --delete story/s{N}.{M}/{slug} 2>/dev/null || true
+```
+
+<verification>
+Story branch deleted (local and remote).
+</verification>
+
+### Step 6: Update Context & Emit
+
+1. Update `CLAUDE.local.md` to reflect completion and next story
+2. Emit telemetry: `rai signal emit-work story S{N}.{M} --event complete`
+3. If the story has a backlog ticket: `rai backlog transition {story_key} done`
+
+| Condition | Action |
+|-----------|--------|
+| Transition succeeds | Continue |
+| Transition fails | Log warning and continue — backlog errors are **non-blocking** for lifecycle |
+| No ticket | Skip backlog transition |
+
+<verification>
+Local context updated. Telemetry emitted.
+</verification>
+
+<if-blocked>
+Adapter not configured or transition fails → log and continue. Backlog sync is best-effort; it must never block story close.
+</if-blocked>
+
+## Output
+
+| Item | Destination |
+|------|-------------|
+| Merge commit | `{dev_branch}` with `--no-ff` |
+| Epic update | `work/epics/e{N}-{name}/scope.md` |
+| Branch cleanup | Story branch deleted |
+| Backlog update | via `rai backlog transition` (best-effort) |
+| Context update | `CLAUDE.local.md` |
+
+## Quality Checklist
+
+- [ ] Retrospective complete before merge (gate)
+- [ ] Tests pass before merge
+- [ ] Merge uses `--no-ff` to preserve story history
+- [ ] Story branch deleted after merge
+- [ ] Epic scope updated with completion status
+- [ ] Working tree clean before merge — no orphaned artifacts
+- [ ] Always merge to `{dev_branch}` — never to an epic branch
+- [ ] NEVER merge without retrospective — learnings compound
+- [ ] NEVER leave stale branches — clean as you go
+
+## References
+
+- Previous: `/rai-story-review`
+- Complement: `/rai-story-start`
+- Epic scope: `work/epics/e{N}-{name}/scope.md`

raise_cli/skills_base/rai-story-design/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: rai-story-design
+description: >
+  Create lean story specifications optimized for both human understanding
+  and AI alignment. Design is not optional (PAT-186) — use before /rai-story-plan
+  for every story to ground integration decisions.
+
+license: MIT
+
+metadata:
+  raise.work_cycle: story
+  raise.frequency: per-story
+  raise.fase: "4"
+  raise.prerequisites: project-backlog
+  raise.next: story-plan
+  raise.gate: ""
+  raise.adaptable: "true"
+  raise.version: "2.3.0"
+  raise.visibility: public
+  raise.output_type: story-design
+  raise.inputs: |
+    - story_md: file_path, required, previous_skill
+    - scope_md: file_path, optional, previous_skill
+  raise.outputs: |
+    - design_yaml: file_path, .raise/artifacts/
+    - design_md: file_path, next_skill
+---
+
+# Story Design
+
+## Purpose
+
+Create a lean story specification optimized for both human review (clear intent) and AI alignment (accurate code generation).
+
+## Mastery Levels (ShuHaRi)
+
+- **Shu**: Follow all steps, include examples for every story
+- **Ha**: Skip optional sections for simple stories, adjust detail to complexity
+- **Ri**: Custom spec patterns for specialized domains
+
+## Context
+
+**When to use:** Before planning any story that involves architectural decisions, multiple approaches, or >3 components.
+
+**When to skip:** Simple stories (<3 components, obvious implementation) → go to `/rai-story-plan`.
+
+**Inputs:** Story from backlog, User Story artifact (`story.md` from `/rai-story-start`), epic scope/design documents.
+
+## Steps
+
+### Step 1: Assess Complexity
+
+| Criterion | Simple | Moderate | Complex |
+|-----------|--------|----------|---------|
+| Components | 1-2 | 3-4 | 5+ |
+| Story points | <5 | 5-8 | >8 |
+| External integrations | 0-1 | 2-3 | 4+ |
+| Algorithm complexity | Trivial | Custom logic | Novel |
+
+| Result | Action |
+|--------|--------|
+| Simple | Skip design → `/rai-story-plan` |
+| Moderate | Core sections only |
+| Complex | Full spec with optional sections |
+
+**Risk gate:** If story is marked HIGH RISK in epic scope, discuss risks before designing — name concerns, failure modes, and scope boundaries.
+
+**UX gate:** If story touches human interaction (workflows, prompts, DX), recommend `/rai-research` first (~10 min, PAT-E-263).
+
+**Integration gate (PAT-E-539):** If story name includes "dogfood", "E2E", or "integration", OR if epic has separate client/server stories developed with mocks — AC MUST include at least one scenario that runs with **real infrastructure** (docker compose, actual DB, real HTTP calls). Unit tests with mocks cannot catch cross-component contract mismatches (auth headers, payload validation, parameter limits).
+
+<verification>
+Complexity assessed. Risk/UX/Integration gates evaluated.
+</verification>
+
+### Step 2: Frame What & Why
+
+Load `story.md` (from `/rai-story-start`) if it exists — use its User Story as starting frame.
+
+- **Problem**: What gap does this fill? (1-2 sentences)
+- **Value**: Why does this matter? (1-2 sentences, measurable or observable)
+
+<verification>
+Can explain to non-technical stakeholder in 30 seconds.
+</verification>
+
+### Step 3: Describe Approach
+
+Document WHAT you're building and WHY this approach (not detailed HOW):
+- Solution approach (1-2 sentences)
+- Components affected (list with change type: create/modify/delete)
+
+**For refactoring:** grep all call sites of the target. A half-migration is worse than none.
+
+**For data mutations:** What happens when inputs reference missing entities? Declare the strategy explicitly: reject with error, skip + report count, partial success with warnings. Silent drops are semantic bugs (PAT-E-523).
+
+**Value preservation gate (PAT-E-572):** Before finalizing components, ask: "What domain knowledge does this layer provide that a generic pass-through wouldn't?" If the answer is "none", the design may be over-abstracted. If the answer involves config/resolution/mapping that an existing pattern handles differently, check where that responsibility lives in the proven pattern. KISS means simplest that serves the purpose — removing domain intelligence to reduce LOC removes the value proposition.
+
+For complex stories, add: scenarios (Gherkin), algorithm pseudocode, constraints, testing strategy.
+
+<verification>
+Approach is concrete enough to envision examples. Value preservation gate passed.
+</verification>
+
+### Step 4: Create Examples (MOST IMPORTANT)
+
+**This section drives AI code generation accuracy more than any other.**
+
+Provide concrete, runnable examples:
+1. **API/CLI usage** — how the story is invoked
+2. **Expected output** — success + error cases
+3. **Data structures** — key models, schemas, types
+
+Use concrete values (not placeholders), correct syntax (not pseudocode), consistent with codebase style.
+
+<verification>
+Examples are concrete, runnable, and cover success + error paths.
+</verification>
+
+<if-blocked>
+Can't envision examples → approach not concrete enough, return to Step 3.
+</if-blocked>
+
+### Step 5: Define Acceptance Criteria
+
+If `story.md` has Gherkin AC, reference them here — refine, don't duplicate. If no `story.md`, define from scratch:
+
+- **MUST**: Required for completion (3-5 items, specific and testable)
+- **SHOULD**: Nice-to-have (1-3 items)
+- **MUST NOT**: Explicit anti-requirements
+
+All criteria must be observable outcomes traceable to value from Step 2.
+
+<verification>
+Criteria are specific, testable, and traceable. Spec reviewable in <5 minutes.
+</verification>
+
+## Output
+
+After completing all steps, produce the design in two locations:
+
+### 1. Typed artifact (source of truth)
+
+Write a YAML artifact to `.raise/artifacts/s{N}.{M}-design.yaml` with this structure:
+
+```yaml
+artifact_type: story-design
+version: 1
+skill: rai-story-design
+created: '{ISO 8601 timestamp}'
+story: 'S{N}.{M}'
+epic: 'E{N}'
+content:
+  summary: '{Problem + Value in 1-2 sentences}'
+  complexity: simple|moderate|complex
+  acceptance_criteria:
+    - id: AC1
+      description: '{criterion text}'
+      verifiable: true
+  integration_points:
+    - module: '{dotted.module.path}'
+      change_type: new|modification|deletion
+      files: ['{relative/path.py}']
+  decisions:
+    - id: D1
+      choice: '{what was chosen}'
+      rationale: '{why}'
+      alternatives_considered: ['{alt1}', '{alt2}']
+refs:
+  backlog_item: '{RAISE-NNN}'
+  epic_scope: 'work/epics/e{N}-{name}/scope.md'
+metadata: {}
+```
+
+### 2. Human-readable Markdown
+
+Write the design as `work/epics/e{N}-{name}/stories/s{N}.{M}-design.md` — colocated with other story artifacts (story.md, scope.md, plan.md, retrospective.md).
+
+| Item | Destination |
+|------|-------------|
+| Typed artifact | `.raise/artifacts/s{N}.{M}-design.yaml` |
+| Design document | `work/epics/e{N}-{name}/stories/s{N}.{M}-design.md` |
+| Next | `/rai-story-plan` |
+
+## Quality Checklist
+
+- [ ] Complexity assessed — design depth matches complexity
+- [ ] What & Why clear in <2 minutes
+- [ ] Examples are concrete and runnable (100% coverage)
+- [ ] Acceptance criteria specific and testable (3-5 MUST items)
+- [ ] Risk/UX/Integration gates evaluated before designing (PAT-E-539)
+- [ ] Data mutation stories declare missing-entity strategy (PAT-E-523)
+- [ ] Value preservation gate: domain intelligence preserved, not simplified away (PAT-E-572)
+- [ ] Spec creation <30 minutes, review <5 minutes
+- [ ] NEVER over-specify HOW — trust AI for implementation details
+- [ ] NEVER skip examples — they are the most important section
+
+## References
+
+- Next: `/rai-story-plan`
+- Risk assessment: PAT-186 (design not optional)
+- UX research gate: PAT-E-263
+- Value preservation gate: PAT-E-572