session-orchestrator 3.16.0

package/.cursor/rules/060-evolve.mdc

@@ -0,0 +1,232 @@
+---
+description: "When the user types /evolve or asks about session learnings, pattern extraction, or learning management"
+globs: ""
+alwaysApply: false
+---
+
+# Evolve — Session Learning Extraction
+
+Extract patterns from session history into reusable learnings. Three modes of operation.
+
+## Prerequisites
+
+- **Persistence gate**: `persistence: true` must be set in Session Config. If not, abort: "Learnings require persistence to be enabled in Session Config."
+- Session history must exist at `.orchestrator/metrics/sessions.jsonl`
+- Learnings are stored at `.orchestrator/metrics/learnings.jsonl`
+- Config field: `learning-expiry-days` (default: 30) — controls `expires_at` for new and updated learnings
+
+## Cursor Adaptation
+
+**No AskUserQuestion tool on Cursor.** Present all choices as numbered Markdown lists:
+```
+Which learnings should be saved?
+
+1. [fragile-file] src/lib/auth.ts — Changed in 4 of last 5 sessions (confidence: 0.5 new)
+2. [scope-guidance] optimal-scope-per-session-type — 3 issues/session works well (+0.15 update)
+3. Skip all — do not save any learnings
+
+Reply with the number(s) of your choice.
+```
+
+## Mode Selection
+
+Determine mode from user input (default: `analyze`):
+
+| Mode | Purpose |
+|------|---------|
+| `analyze` | Extract new learnings from session history |
+| `review` | Edit/manage existing learnings interactively |
+| `list` | Display active learnings (read-only) |
+
+---
+
+## Mode 1: Analyze
+
+Extract learnings from `.orchestrator/metrics/sessions.jsonl`.
+
+### Step 1: Load Session Data
+
+1. Read all entries from `sessions.jsonl`, parse each line as JSON
+2. Sort by `completed_at` descending (most recent first)
+3. If no sessions found, abort: "No session data available."
+
+### Step 2: Pattern Extraction
+
+Apply these heuristics for each learning type:
+
+#### fragile-file
+- Same file appears in 3+ waves' `files_changed` within a session, or in 3+ different sessions
+- Subject = relative file path
+
+#### effective-sizing
+- Compare `total_agents` and `total_waves` across session types
+- Calculate average agents per wave per session type
+- Subject = e.g. `deep-session-sizing` or `feature-session-sizing`
+
+#### recurring-issue
+- `agent_summary` shows `failed` or `partial` > 0 across multiple sessions
+- Repeated failures in wave `quality` fields
+- Subject = issue pattern identifier (e.g. `test-failures-in-wave-execution`)
+
+#### scope-guidance
+- Cross-reference `effectiveness.planned_issues` vs `effectiveness.completion_rate`
+- Skip sessions lacking the `effectiveness` field
+- If completion_rate consistently 1.0 with N issues: "N issues per session works well"
+- If completion_rate < 0.7: "scope was too large"
+- Subject = `optimal-scope-per-session-type`
+
+#### deviation-pattern
+- Read `.cursor/STATE.md` if it exists, check `## Deviations` section
+- Cross-reference session duration vs planned waves
+- Subject = pattern name (e.g. `scope-creep-in-feature-sessions`)
+
+### Step 3: Deduplicate
+
+For each extracted pattern, check if a learning with same `type` + `subject` exists in `learnings.jsonl`:
+- **Exists:** propose confidence update (+0.15 if confirmed, -0.2 if contradicted)
+- **New:** propose as new learning with confidence 0.5
+
+### Step 4: Present to User
+
+Present extracted patterns as a numbered Markdown list (see Cursor Adaptation above). Let the user select which to save. Include a "Skip all" option.
+
+If user skips or selects nothing: "No learnings saved."
+
+If zero patterns were extracted, report: "No patterns found in session history." and stop.
+
+### Step 5: Write Confirmed Learnings
+
+Use atomic rewrite strategy:
+1. Read ALL existing lines from `learnings.jsonl` into memory
+2. Apply confidence updates for confirmed existing learnings (+0.15, cap at 1.0)
+3. Apply confidence decrements for contradicted learnings (-0.2)
+4. Append new learnings with confidence 0.5
+5. Prune entries where `expires_at` < current date OR `confidence` <= 0.0
+6. Consolidate duplicates (same `type` + `subject`): keep highest confidence
+7. Write entire result back with `>` (atomic rewrite, NOT append `>>`)
+
+Report: "Saved N new learnings, updated M existing. Total active: K."
+
+---
+
+## Mode 2: Review
+
+Interactive management of existing learnings.
+
+### Step 1: Load and Display
+
+Read `learnings.jsonl`. If empty or missing: "No learnings found. Run `/evolve analyze` first."
+
+Display as a formatted table grouped by type:
+
+```
+## Active Learnings
+
+| # | Type | Subject | Confidence | Expires | Insight |
+|---|------|---------|------------|---------|---------|
+| 1 | fragile-file | src/lib/auth.ts | 0.80 | 2026-07-05 | Changed in 4 of last 5 sessions |
+
+Summary: N active learnings (M high confidence, K expiring soon)
+```
+
+### Step 2: Interactive Management
+
+Present as a numbered Markdown list (see Cursor Adaptation above):
+- **Boost confidence** — select learnings to boost (+0.15, cap 1.0)
+- **Reduce confidence** — select learnings to reduce (-0.2)
+- **Delete specific learnings** — remove selected entries
+- **Extend expiry** — reset `expires_at` to current date + `learning-expiry-days`
+- **Done** — exit without changes
+
+### Step 3: Apply Changes
+
+Same atomic rewrite strategy as analyze mode. Read all, modify selected, prune, consolidate, write all with `>`.
+
+Report: "Updated N learnings. Total active: K."
+
+---
+
+## Mode 3: List
+
+Read-only display of active learnings.
+
+### Output Format
+
+Display grouped by type:
+
+```
+## Active Learnings
+
+### fragile-file
+| Subject | Confidence | Expires | Insight |
+|---------|------------|---------|---------|
+
+### effective-sizing
+| Subject | Confidence | Expires | Insight |
+|---------|------------|---------|---------|
+
+(repeat for each type with entries)
+```
+
+### Summary Line
+
+```
+N active learnings (M high confidence, K expiring soon)
+```
+
+- **High confidence** = confidence > 0.7
+- **Expiring soon** = `expires_at` within 14 days of current date
+
+---
+
+## Learning JSONL Format
+
+Each line in `.orchestrator/metrics/learnings.jsonl` is a JSON object:
+
+```json
+{
+  "id": "uuid-v4",
+  "type": "fragile-file|effective-sizing|recurring-issue|scope-guidance|deviation-pattern",
+  "subject": "identifier for the pattern",
+  "insight": "human-readable description",
+  "evidence": "specific data points supporting the pattern",
+  "confidence": 0.5,
+  "source_session": "session-id",
+  "created_at": "2026-04-07T00:00:00Z",
+  "expires_at": "2026-05-07T00:00:00Z"
+}
+```
+
+### Confidence Lifecycle
+
+| Event | Change |
+|-------|--------|
+| Created | 0.5 |
+| Confirmed (new evidence or user boost) | +0.15 (cap 1.0) |
+| Contradicted or user reduce | -0.2 |
+| Past `expires_at` date | Pruned on next write |
+| Confidence <= 0.0 | Pruned on next write |
+
+### Valid Learning Types
+
+| Type | What it captures |
+|------|-----------------|
+| `fragile-file` | Files changed too frequently across sessions/waves |
+| `effective-sizing` | Optimal agent/wave sizing per session type |
+| `recurring-issue` | Repeated failures or partial completions |
+| `scope-guidance` | How many issues fit well in a session |
+| `deviation-pattern` | Scope creep, underestimation, plan deviations |
+
+---
+
+## Critical Rules
+
+- NEVER modify `learnings.jsonl` without reading it first
+- NEVER skip deduplication (check `type` + `subject` match)
+- NEVER write learnings without user confirmation
+- ALWAYS use uuid-v4 for new learning IDs (generate via `uuidgen`)
+- ALWAYS set `expires_at` to current date + `learning-expiry-days` from config (default: 30)
+- ALWAYS use atomic rewrite (read all, modify, write all with `>`)
+- ALWAYS cap confidence at 1.0
+- NEVER fabricate patterns -- only extract from actual session data with verifiable evidence
+- NEVER append to `learnings.jsonl` with `>>` -- always atomic rewrite

package/.cursor/rules/070-gitlab-ops.mdc

@@ -0,0 +1,246 @@
+---
+description: "When working with GitLab or GitHub — issues, merge requests, pull requests, CI pipelines, labels"
+globs: ""
+alwaysApply: false
+---
+
+# VCS Operations Reference (GitLab & GitHub)
+
+Single source of truth for all VCS CLI commands, label taxonomy, issue templates, and project resolution.
+
+## VCS Auto-Detection
+
+Detect which platform the current repo uses:
+
+```bash
+REMOTE_URL=$(git remote get-url origin 2>/dev/null)
+if echo "$REMOTE_URL" | grep -q "github.com"; then
+  VCS=github    # use `gh`
+else
+  VCS=gitlab    # use `glab`
+fi
+```
+
+Session Config overrides:
+- `vcs: github|gitlab` -- force a specific platform
+- `gitlab-host: <host>` -- override auto-detected GitLab host
+
+## Dynamic Project Resolution
+
+Never hardcode project IDs. Resolve at runtime.
+
+### Current Project
+
+```bash
+# GitLab — numeric project ID
+glab repo view --output json | python3 -c "import json,sys; print(json.load(sys.stdin)['id'])"
+
+# GitHub — owner/name
+gh repo view --json nameWithOwner -q '.nameWithOwner'
+```
+
+### Cross-Project Queries
+
+```bash
+# GitLab — resolve by name
+glab api "projects?search=<project-name>" | python3 -c "import json,sys; [print(p['id'], p['path_with_namespace']) for p in json.load(sys.stdin)]"
+
+# GitHub — resolve repo details
+gh api "repos/<owner>/<name>" --jq '.full_name'
+```
+
+---
+
+## Common CLI Commands
+
+### GitLab (glab)
+
+```bash
+# Issues
+glab issue list --per-page 50                              # All open issues
+glab issue list --label "status:ready" --per-page 10       # Filtered by label
+glab issue list --label "priority:high" --per-page 10      # High priority
+glab issue list --closed --per-page 10                     # Recently closed
+glab issue view <IID>                                      # View issue details
+glab issue view <IID> --comments                           # With comments
+glab issue create --title "title" --label "priority:high,status:ready"
+glab issue update <IID> --label "status:in-progress"
+glab issue close <IID>
+glab issue note <IID> -m "Comment text"                    # Add comment
+
+# MRs
+glab mr list                                               # Open MRs
+glab mr create --fill --draft                              # Create draft MR
+glab mr merge <MR_IID>                                     # Merge MR
+
+# Pipelines
+glab pipeline list --per-page 5                            # Recent pipelines
+glab pipeline status <ID>                                  # Pipeline details
+
+# API (reads host from git remote automatically)
+PROJECT_ID=$(glab repo view --output json | python3 -c "import json,sys; print(json.load(sys.stdin)['id'])")
+glab api "projects/$PROJECT_ID/issues?state=opened&per_page=50"
+glab api "projects/$PROJECT_ID/milestones?state=active"
+```
+
+### GitHub (gh)
+
+```bash
+# Issues
+gh issue list --limit 50                                   # All open issues
+gh issue list --label "status:ready" --limit 10            # Filtered by label
+gh issue list --label "priority:high" --limit 10           # High priority
+gh issue list --state closed --limit 10                    # Recently closed
+gh issue view <NUMBER>                                     # View issue details
+gh issue view <NUMBER> --comments                          # With comments
+gh issue create --title "title" --label "priority:high,status:ready"
+gh issue edit <NUMBER> --add-label "status:in-progress"
+gh issue close <NUMBER>
+gh issue comment <NUMBER> --body "Comment text"            # Add comment
+
+# PRs
+gh pr list --state open                                    # Open PRs
+gh pr create --fill --draft                                # Create draft PR
+gh pr merge <NUMBER>                                       # Merge PR
+
+# Workflows (CI)
+gh run list --limit 5                                      # Recent workflow runs
+gh run view <RUN_ID>                                       # Run details
+
+# API
+gh api "repos/{owner}/{repo}/issues?state=open&per_page=50"
+gh api "repos/{owner}/{repo}/milestones?state=open"
+```
+
+---
+
+## glab CLI Quirks
+
+These are known differences from `gh` that cause frequent mistakes:
+
+| Quirk | Correct | Wrong |
+|-------|---------|-------|
+| Listing closed issues | `glab issue list --closed` | `glab issue list --state closed` |
+| Confirmations | glab has NO `--yes` flag | Do not pass `--yes` |
+| Comprehensive listing | `glab issue list --per-page 100` | Default per-page is small |
+| Pagination flag | `--per-page N` (glab) | `--limit N` (that is gh syntax) |
+
+---
+
+## Label Taxonomy
+
+### Priority Labels
+- `priority:critical` -- blocking production or users
+- `priority:high` -- important, schedule this sprint
+- `priority:medium` -- plan for next sprint
+- `priority:low` -- backlog, nice-to-have
+
+### Status Labels
+- `status:ready` -- defined, ready to pick up
+- `status:in-progress` -- actively being worked on
+- `status:review` -- MR/PR created, awaiting review
+- `status:blocked` -- waiting on external dependency
+
+### Area Labels
+- `area:frontend` | `area:backend` | `area:database`
+- `area:ai` | `area:security` | `area:testing`
+- `area:ci` | `area:infrastructure` | `area:compliance`
+- `area:skills` | `area:vcs` | `area:harness`
+
+### Type Labels
+- `bug` | `feature` | `enhancement` | `refactor`
+- `chore` | `documentation` | `epic` | `discovery`
+
+---
+
+## Issue Templates
+
+### Bug
+
+```markdown
+## Description
+What happens vs. what should happen.
+
+## Steps to Reproduce
+1.
+2.
+
+## Root Cause (if known)
+
+## Acceptance Criteria
+- [ ]
+```
+
+### Feature
+
+```markdown
+## Goal
+What should be achieved and why.
+
+## Tasks
+- [ ]
+
+## Acceptance Criteria
+- [ ]
+
+## Session Type
+[housekeeping|feature|deep]
+```
+
+### Carryover (from /close)
+
+```markdown
+## [Carryover] Original Task Description
+
+### What was completed
+- [completed items]
+
+### What remains
+- [ ] [remaining task 1]
+- [ ] [remaining task 2]
+
+### Context for next session
+[relevant context, file paths, decisions made]
+
+### Original Issue
+Relates to #ORIGINAL_IID
+```
+
+### Discovery Finding
+
+```markdown
+## [Discovery] <finding title>
+
+**Probe:** <probe_name>
+**Severity:** <priority:critical|high|medium|low>
+**Category:** <code|infra|ui|arch|session|audit|vault|feature>
+
+### Finding
+<description of the problem>
+
+### Evidence
+- **File:** `<file_path>`
+- **Line:** <line_number>
+- **Code:**
+  ```
+  <matched_text with surrounding context>
+  ```
+
+### Impact
+<why this matters>
+
+### Recommended Fix
+<concrete fix suggestion>
+
+### Acceptance Criteria
+- [ ] <specific, verifiable condition>
+- [ ] Quality gates pass after fix
+```
+
+Labels for discovery findings: `type:discovery`, `priority:<level>`, `area:<inferred>`, `status:ready`
+
+
+
+---
+
+CI pipeline commands are listed in the Common CLI Commands section above (Pipelines/Workflows). Interpret: green=passed, red=failed (investigate before proceeding), pending=in progress.

package/.cursor/rules/080-ecosystem-health.mdc

@@ -0,0 +1,145 @@
+---
+description: "When checking service health, CI pipeline status, endpoint availability, or cross-repo status"
+globs: ""
+alwaysApply: false
+---
+
+# Ecosystem Health Check
+
+Monitor health across configured service endpoints, CI pipelines, and critical issues. Automatically invoked during session-start when ecosystem-health is enabled in Session Config.
+
+## Session Config Fields
+
+This skill reads from the project's `## Session Config` section:
+
+- **`health-endpoints`** -- list of `{name, url}` objects for service health checks
+- **`cross-repos`** -- list of related repositories for critical issue scanning
+
+Both fields are optional. The skill degrades gracefully when either is missing.
+
+---
+
+## 1. Service Health
+
+Read `health-endpoints` from Session Config. If not configured or empty:
+
+> "No health endpoints configured in Session Config. Add `health-endpoints` to enable service monitoring."
+
+Skip this section and proceed to CI Pipeline Status.
+
+### Health Check Procedure
+
+For each configured endpoint:
+
+```bash
+# Example config:
+#   health-endpoints:
+#     - name: API
+#       url: https://api.example.com/health
+#     - name: Worker
+#       url: http://worker:8080/healthz
+
+# Basic check
+curl -sf <url> 2>/dev/null && echo "<name>: UP" || echo "<name>: DOWN"
+
+# If endpoint returns JSON with a "status" field, extract it:
+curl -sf <url> 2>/dev/null | python3 -c "
+import json,sys
+d=json.load(sys.stdin)
+print(f'<name>: {d.get(\"status\",\"OK\")}')
+" 2>/dev/null || echo "<name>: DOWN"
+```
+
+Generate check commands dynamically from config. Never hardcode service names or URLs.
+
+### Status Classification
+
+| Status | Meaning |
+|--------|---------|
+| **UP** | Endpoint responded successfully |
+| **DOWN** | Endpoint unreachable or returned error |
+| **DEGRADED** | Endpoint responded but reported unhealthy status in JSON body |
+
+---
+
+## 2. CI Pipeline Status
+
+Query the latest pipeline/workflow runs for the current repo. Report the 3 most recent runs.
+
+### VCS Detection
+
+Detect the VCS platform per the VCS Auto-Detection section of the gitlab-ops rule. Then use the appropriate CLI:
+
+```bash
+# GitLab
+glab pipeline list --per-page 3
+
+# GitHub
+gh run list --limit 3
+```
+
+Report each run with: status (success/failed/pending), branch, and timestamp.
+
+---
+
+## 3. Critical Issues
+
+Read `cross-repos` from Session Config. If not configured or empty:
+
+> "No cross-repos configured in Session Config. Add `cross-repos` to enable cross-project issue scanning."
+
+Skip this section.
+
+### Cross-Repo Issue Scan
+
+For each repo in `cross-repos`:
+
+1. Resolve project ID or owner/repo slug (see gitlab-ops Dynamic Project Resolution)
+2. Query open issues with `priority:critical` or `priority:high` labels (limit 5 per repo)
+3. Collect and report results across all configured repos
+
+```bash
+# GitLab
+glab api "projects/<PROJECT_ID>/issues?labels=priority:critical,priority:high&state=opened&per_page=5"
+
+# GitHub
+gh issue list --repo <owner/repo> --label "priority:critical" --limit 5
+gh issue list --repo <owner/repo> --label "priority:high" --limit 5
+```
+
+---
+
+## 4. Health Report Format
+
+Present as a compact dashboard:
+
+```
+## Ecosystem Health
+
+| Service | Status |
+|---------|--------|
+| API     | UP     |
+| Worker  | DOWN   |
+| DB      | UP     |
+
+CI Pipeline: green (last 3 runs passed)
+Critical Issues: 2 across 3 repos
+
+### Attention Required
+- Worker service is DOWN
+- 2 critical issues in cross-repos (see details below)
+```
+
+### Conditional Sections
+
+- If no `health-endpoints` configured: omit the service table entirely
+- If no `cross-repos` configured: omit the critical issues section
+- Only show "Attention Required" if any service is DOWN/DEGRADED or critical issue count > 0
+
+### Status Indicators
+
+| Indicator | Condition |
+|-----------|-----------|
+| All clear | All services UP, CI green, no critical issues |
+| Warning | Any service DEGRADED or CI pending |
+| Alert | Any service DOWN, CI failed, or critical issues exist |

package/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "session-orchestrator": {
+      "command": "bash",
+      "args": ["-c", "exec bash \"${CLAUDE_PLUGIN_ROOT:-${CODEX_PLUGIN_ROOT:-$(git rev-parse --show-toplevel)}}/scripts/mcp-server.sh\""]
+    }
+  }
+}