loki-mode 6.9.0 → 6.11.0

package/autonomy/prd-analyzer.py

@@ -252,7 +252,7 @@ class PrdAnalyzer:
         count = 0
         in_feature_section = False
         for line in self.lines:
-            if re.search(r"(?i)#+\s.*(?:feature|requirement|scope|functional)", line):
+            if re.search(r"(?i)#+\s.*(?:feature|requirement|scope|functional|module|component|service|endpoint|api|milestone|deliverable|workstream|epic|story|task|phase|capability|objective)", line):
                 in_feature_section = True
                 continue
             if in_feature_section and re.match(r"^\s*#+\s", line):
@@ -262,12 +262,25 @@ class PrdAnalyzer:
                 if re.match(r"^\s*[-*]\s+\S", line) or re.match(r"^\s*\d+\.\s+\S", line):
                     count += 1
 
+        # Fallback: count ## headings as feature indicators when bullet items are few
+        if count == 0:
+            for line in self.lines:
+                if re.match(r"^##\s+\S", line):
+                    count += 1
+
         self.feature_count = count
         for threshold, label in SCOPE_THRESHOLDS:
             if count <= threshold:
                 self.scope = label
                 break
 
+        # Word-count fallback: large PRDs should never be classified as small
+        word_count = len(self.content.split())
+        if word_count > 2000 and self.scope in ("small", "medium"):
+            self.scope = "large"
+        elif word_count > 500 and self.scope == "small":
+            self.scope = "medium"
+
     def generate_observations(self):
         """Generate the observations markdown content."""
         now = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")

package/autonomy/run.sh

@@ -622,6 +622,11 @@ MAX_WORKTREES=${LOKI_MAX_WORKTREES:-5}
 MAX_PARALLEL_SESSIONS=${LOKI_MAX_PARALLEL_SESSIONS:-3}
 PARALLEL_TESTING=${LOKI_PARALLEL_TESTING:-true}
 PARALLEL_DOCS=${LOKI_PARALLEL_DOCS:-true}
+
+# Gate Escalation Ladder (v6.10.0)
+GATE_CLEAR_LIMIT=${LOKI_GATE_CLEAR_LIMIT:-3}
+GATE_ESCALATE_LIMIT=${LOKI_GATE_ESCALATE_LIMIT:-5}
+GATE_PAUSE_LIMIT=${LOKI_GATE_PAUSE_LIMIT:-10}
 TARGET_DIR="${LOKI_TARGET_DIR:-$(pwd)}"
 PARALLEL_BLOG=${LOKI_PARALLEL_BLOG:-false}
 AUTO_MERGE=${LOKI_AUTO_MERGE:-true}
@@ -5250,6 +5255,69 @@ SAFEOF
     fi
 }
 
+#===============================================================================
+# Gate Failure Tracking (v6.10.0)
+#===============================================================================
+
+track_gate_failure() {
+    local gate_name="$1"
+    local gate_file="${TARGET_DIR:-.}/.loki/quality/gate-failure-count.json"
+    mkdir -p "$(dirname "$gate_file")"
+
+    _GATE_FILE="$gate_file" _GATE_NAME="$gate_name" python3 -c "
+import json, os
+gate_file = os.environ['_GATE_FILE']
+gate_name = os.environ['_GATE_NAME']
+try:
+    with open(gate_file) as f:
+        counts = json.load(f)
+except (json.JSONDecodeError, FileNotFoundError, OSError):
+    counts = {}
+counts[gate_name] = counts.get(gate_name, 0) + 1
+with open(gate_file, 'w') as f:
+    json.dump(counts, f, indent=2)
+print(counts[gate_name])
+" 2>/dev/null || echo "1"
+}
+
+clear_gate_failure() {
+    local gate_name="$1"
+    local gate_file="${TARGET_DIR:-.}/.loki/quality/gate-failure-count.json"
+    [ -f "$gate_file" ] || return 0
+
+    _GATE_FILE="$gate_file" _GATE_NAME="$gate_name" python3 -c "
+import json, os
+gate_file = os.environ['_GATE_FILE']
+gate_name = os.environ['_GATE_NAME']
+try:
+    with open(gate_file) as f:
+        counts = json.load(f)
+except (json.JSONDecodeError, FileNotFoundError, OSError):
+    counts = {}
+counts[gate_name] = 0
+with open(gate_file, 'w') as f:
+    json.dump(counts, f, indent=2)
+" 2>/dev/null || true
+}
+
+get_gate_failure_count() {
+    local gate_name="$1"
+    local gate_file="${TARGET_DIR:-.}/.loki/quality/gate-failure-count.json"
+    [ -f "$gate_file" ] || { echo "0"; return; }
+
+    _GATE_FILE="$gate_file" _GATE_NAME="$gate_name" python3 -c "
+import json, os
+gate_file = os.environ['_GATE_FILE']
+gate_name = os.environ['_GATE_NAME']
+try:
+    with open(gate_file) as f:
+        counts = json.load(f)
+    print(counts.get(gate_name, 0))
+except (json.JSONDecodeError, FileNotFoundError, OSError):
+    print(0)
+" 2>/dev/null || echo "0"
+}
+
 # ============================================================================
 # Hard Quality Gate: Test Coverage (v6.7.0)
 # Detects test runner and runs tests with coverage reporting
@@ -5287,6 +5355,58 @@ enforce_test_coverage() {
         fi
     fi
 
+    # Monorepo: scan workspace packages for test runners (v6.10.0)
+    if [ "$test_runner" = "none" ] && [ -f "${TARGET_DIR:-.}/package.json" ]; then
+        local is_monorepo=false
+        # Detect monorepo indicators
+        if [ -f "${TARGET_DIR:-.}/pnpm-workspace.yaml" ] || \
+           [ -f "${TARGET_DIR:-.}/turbo.json" ] || \
+           [ -f "${TARGET_DIR:-.}/lerna.json" ] || \
+           grep -q '"workspaces"' "${TARGET_DIR:-.}/package.json" 2>/dev/null; then
+            is_monorepo=true
+        fi
+
+        if [ "$is_monorepo" = "true" ]; then
+            # Allow env override
+            if [ -n "${LOKI_MONOREPO_TEST_CMD:-}" ]; then
+                test_runner="monorepo-custom"
+                local output
+                output=$(cd "${TARGET_DIR:-.}" && eval "$LOKI_MONOREPO_TEST_CMD" 2>&1) || test_passed=false
+                details="monorepo-custom: $(echo "$output" | tail -3 | tr '\n' ' ')"
+            else
+                # Scan workspace packages for test runners
+                local workspace_runner=""
+                for pkg_json in "${TARGET_DIR:-.}"/packages/*/package.json \
+                                "${TARGET_DIR:-.}"/apps/*/package.json \
+                                "${TARGET_DIR:-.}"/services/*/package.json; do
+                    [ -f "$pkg_json" ] || continue
+                    if grep -q '"vitest"' "$pkg_json" 2>/dev/null; then
+                        workspace_runner="vitest"
+                        break
+                    elif grep -q '"jest"' "$pkg_json" 2>/dev/null; then
+                        workspace_runner="jest"
+                        break
+                    fi
+                done
+
+                if [ -n "$workspace_runner" ]; then
+                    test_runner="monorepo-$workspace_runner"
+                    local output
+                    if [ -f "${TARGET_DIR:-.}/turbo.json" ] && command -v turbo &>/dev/null; then
+                        output=$(cd "${TARGET_DIR:-.}" && npx turbo test 2>&1) || test_passed=false
+                        details="turbo test ($workspace_runner): $(echo "$output" | tail -3 | tr '\n' ' ')"
+                    elif [ -f "${TARGET_DIR:-.}/pnpm-workspace.yaml" ] && command -v pnpm &>/dev/null; then
+                        output=$(cd "${TARGET_DIR:-.}" && pnpm test --recursive 2>&1) || test_passed=false
+                        details="pnpm test --recursive ($workspace_runner): $(echo "$output" | tail -3 | tr '\n' ' ')"
+                    else
+                        output=$(cd "${TARGET_DIR:-.}" && npm test 2>&1) || test_passed=false
+                        details="npm test ($workspace_runner): $(echo "$output" | tail -3 | tr '\n' ' ')"
+                    fi
+                fi
+            fi
+        fi
+    fi
+
     # Python
     if [ "$test_runner" = "none" ]; then
         if [ -f "${TARGET_DIR:-.}/setup.py" ] || [ -f "${TARGET_DIR:-.}/pyproject.toml" ] || \
@@ -7398,11 +7518,16 @@ build_prompt() {
     if [ -n "$COMPLETION_PROMISE" ]; then
         completion_instruction="COMPLETION_PROMISE: [$COMPLETION_PROMISE]. ONLY output 'COMPLETION PROMISE FULFILLED: $COMPLETION_PROMISE' when this EXACT condition is met."
     else
-        completion_instruction="NO COMPLETION PROMISE SET. Run forever finding improvements. Iteration $iteration of max $MAX_ITERATIONS."
+        completion_instruction="NO COMPLETION PROMISE SET. Continue finding improvements. The Completion Council will evaluate your progress periodically. Iteration $iteration of max $MAX_ITERATIONS."
     fi
 
     # Core autonomous instructions - NO questions, NO waiting, NEVER say done
-    local autonomous_suffix="CRITICAL AUTONOMY RULES: 1) NEVER ask questions - just decide. 2) NEVER wait for confirmation - just act. 3) NEVER say 'done' or 'complete' - there's always more to improve. 4) NEVER stop voluntarily - if out of tasks, create new ones (add tests, optimize, refactor, add features). 5) Work continues PERPETUALLY. Even if PRD is implemented, find bugs, add tests, improve UX, optimize performance."
+    local autonomous_suffix=""
+    if [ "$AUTONOMY_MODE" = "perpetual" ] || [ "$PERPETUAL_MODE" = "true" ]; then
+        autonomous_suffix="CRITICAL AUTONOMY RULES: 1) NEVER ask questions - just decide. 2) NEVER wait for confirmation - just act. 3) NEVER say 'done' or 'complete' - there's always more to improve. 4) NEVER stop voluntarily - if out of tasks, create new ones (add tests, optimize, refactor, add features). 5) Work continues PERPETUALLY. Even if PRD is implemented, find bugs, add tests, improve UX, optimize performance."
+    else
+        autonomous_suffix="CRITICAL AUTONOMY RULES: 1) NEVER ask questions - just decide. 2) NEVER wait for confirmation - just act. 3) When all PRD requirements are implemented and tests pass, output the completion promise text EXACTLY: '$COMPLETION_PROMISE'. 4) If out of tasks but PRD is not fully implemented, continue working on remaining requirements. 5) Focus on completing PRD scope, not endless improvements."
+    fi
 
     # Skill files are always copied to .loki/skills/ for all providers
     local sdlc_instruction="SDLC_PHASES_ENABLED: [$phases]. Execute ALL enabled phases. Log results to .loki/logs/. See .loki/SKILL.md for phase details. Skill modules at .loki/skills/."
@@ -7585,6 +7710,29 @@ except: pass
         fi
     fi
 
+    # OpenSpec delta context injection (if available)
+    local openspec_context=""
+    if [[ -f ".loki/openspec/delta-context.json" ]]; then
+        openspec_context=$(_DELTA_FILE=".loki/openspec/delta-context.json" python3 -c "
+import json, os
+try:
+    with open(os.environ['_DELTA_FILE']) as f:
+        data = json.load(f)
+    parts = ['OPENSPEC DELTA CONTEXT:']
+    for domain, deltas in data.get('deltas', {}).items():
+        for req in deltas.get('added', []):
+            parts.append(f'  ADDED [{domain}]: {req[\"name\"]} - Create new code following existing patterns')
+        for req in deltas.get('modified', []):
+            parts.append(f'  MODIFIED [{domain}]: {req[\"name\"]} - Find and update existing code, do NOT create new files. Previously: {req.get(\"previously\", \"N/A\")}')
+        for req in deltas.get('removed', []):
+            parts.append(f'  REMOVED [{domain}]: {req[\"name\"]} - Deprecate or remove. Reason: {req.get(\"reason\", \"N/A\")}')
+    parts.append(f'Complexity: {data.get(\"complexity\", \"unknown\")}')
+    print(' '.join(parts))
+except Exception:
+    pass
+" 2>/dev/null || true)
+    fi
+
     # Degraded providers with small models need simplified prompts
     # Full RARV/SDLC instructions overwhelm models < 30B parameters
     if [ "${PROVIDER_DEGRADED:-false}" = "true" ]; then
@@ -7609,15 +7757,15 @@ except: pass
     else
         if [ $retry -eq 0 ]; then
             if [ -n "$prd" ]; then
-                echo "Loki Mode with PRD at $prd. $human_directive $gate_failure_context $queue_tasks $bmad_context $checklist_status $app_runner_info $playwright_info $memory_context_section $rarv_instruction $memory_instruction $compaction_reminder $completion_instruction $sdlc_instruction $autonomous_suffix"
+                echo "Loki Mode with PRD at $prd. $human_directive $gate_failure_context $queue_tasks $bmad_context $openspec_context $checklist_status $app_runner_info $playwright_info $memory_context_section $rarv_instruction $memory_instruction $compaction_reminder $completion_instruction $sdlc_instruction $autonomous_suffix"
             else
-                echo "Loki Mode. $human_directive $gate_failure_context $queue_tasks $bmad_context $checklist_status $app_runner_info $playwright_info $memory_context_section $analysis_instruction $rarv_instruction $memory_instruction $compaction_reminder $completion_instruction $sdlc_instruction $autonomous_suffix"
+                echo "Loki Mode. $human_directive $gate_failure_context $queue_tasks $bmad_context $openspec_context $checklist_status $app_runner_info $playwright_info $memory_context_section $analysis_instruction $rarv_instruction $memory_instruction $compaction_reminder $completion_instruction $sdlc_instruction $autonomous_suffix"
             fi
         else
             if [ -n "$prd" ]; then
-                echo "Loki Mode - Resume iteration #$iteration (retry #$retry). PRD: $prd. $human_directive $gate_failure_context $queue_tasks $bmad_context $checklist_status $app_runner_info $playwright_info $memory_context_section $rarv_instruction $memory_instruction $compaction_reminder $completion_instruction $sdlc_instruction $autonomous_suffix"
+                echo "Loki Mode - Resume iteration #$iteration (retry #$retry). PRD: $prd. $human_directive $gate_failure_context $queue_tasks $bmad_context $openspec_context $checklist_status $app_runner_info $playwright_info $memory_context_section $rarv_instruction $memory_instruction $compaction_reminder $completion_instruction $sdlc_instruction $autonomous_suffix"
             else
-                echo "Loki Mode - Resume iteration #$iteration (retry #$retry). $human_directive $gate_failure_context $queue_tasks $bmad_context $checklist_status $app_runner_info $playwright_info $memory_context_section Use .loki/generated-prd.md if exists. $rarv_instruction $memory_instruction $compaction_reminder $completion_instruction $sdlc_instruction $autonomous_suffix"
+                echo "Loki Mode - Resume iteration #$iteration (retry #$retry). $human_directive $gate_failure_context $queue_tasks $bmad_context $openspec_context $checklist_status $app_runner_info $playwright_info $memory_context_section Use .loki/generated-prd.md if exists. $rarv_instruction $memory_instruction $compaction_reminder $completion_instruction $sdlc_instruction $autonomous_suffix"
             fi
         fi
     fi
@@ -7742,6 +7890,91 @@ BMAD_QUEUE_EOF
     log_info "BMAD queue population complete"
 }
 
+#===============================================================================
+# OpenSpec Task Queue Population
+#===============================================================================
+
+# Populate the task queue from OpenSpec task artifacts
+# Only runs once -- skips if queue was already populated from OpenSpec
+populate_openspec_queue() {
+    # Skip if no OpenSpec tasks file
+    if [[ ! -f ".loki/openspec-tasks.json" ]]; then
+        return 0
+    fi
+
+    # Skip if already populated (marker file)
+    if [[ -f ".loki/queue/.openspec-populated" ]]; then
+        log_info "OpenSpec queue already populated, skipping"
+        return 0
+    fi
+
+    log_step "Populating task queue from OpenSpec tasks..."
+
+    # Ensure queue directory exists
+    mkdir -p ".loki/queue"
+
+    # Read OpenSpec tasks and create queue entries
+    python3 << 'OPENSPEC_QUEUE_EOF'
+import json
+import sys
+
+openspec_tasks_path = ".loki/openspec-tasks.json"
+pending_path = ".loki/queue/pending.json"
+
+try:
+    with open(openspec_tasks_path, "r") as f:
+        openspec_tasks = json.load(f)
+except (json.JSONDecodeError, FileNotFoundError) as e:
+    print(f"Warning: Could not read OpenSpec tasks: {e}", file=sys.stderr)
+    sys.exit(0)
+
+# Load existing queue
+existing = []
+try:
+    with open(pending_path, "r") as f:
+        existing = json.load(f)
+except (json.JSONDecodeError, FileNotFoundError):
+    pass
+
+# Convert OpenSpec tasks to queue format (skip completed tasks)
+for task in openspec_tasks:
+    if task.get("status") == "completed":
+        continue
+    queue_entry = {
+        "id": task.get("id", "openspec-unknown"),
+        "title": task.get("title", "Untitled"),
+        "description": f"[OpenSpec] {task.get('group', 'General')}: {task.get('title', '')}",
+        "priority": task.get("priority", "medium"),
+        "status": "pending",
+        "source": "openspec",
+        "metadata": {
+            "openspec_source": task.get("source", "tasks.md"),
+            "openspec_group": task.get("group", ""),
+        }
+    }
+    existing.append(queue_entry)
+
+with open(pending_path, "w") as f:
+    json.dump(existing, f, indent=2)
+
+pending_count = sum(1 for t in openspec_tasks if t.get('status') != 'completed')
+if pending_count == 0:
+    print("WARNING: All OpenSpec tasks are already marked as completed. No tasks added to queue.", file=sys.stderr)
+    print("Check your tasks.md file -- all checkboxes are checked.", file=sys.stderr)
+else:
+    print(f"Added {pending_count} OpenSpec tasks to queue")
+OPENSPEC_QUEUE_EOF
+
+    if [[ $? -ne 0 ]]; then
+        log_warn "Failed to populate OpenSpec queue (python3 error)"
+        return 0
+    fi
+
+    # Mark as populated so we don't re-add on restart
+    touch ".loki/queue/.openspec-populated"
+    log_info "OpenSpec queue population complete"
+}
+
 #===============================================================================
 # Main Autonomous Loop
 #===============================================================================
@@ -7823,9 +8056,27 @@ run_autonomous() {
         fi
     fi
 
+    # Auto-derive completion promise from PRD (v6.10.0)
+    # When PRD exists but no explicit promise, auto-derive one and switch to checkpoint mode
+    if [ -n "$prd_path" ] && [ -f "$prd_path" ] && [ -z "$COMPLETION_PROMISE" ]; then
+        if [ "${LOKI_AUTO_COMPLETION_PROMISE:-true}" = "true" ]; then
+            COMPLETION_PROMISE="All PRD requirements implemented and tests passing"
+            log_info "Auto-derived completion promise: $COMPLETION_PROMISE"
+            # PRD-driven work is finite; switch from perpetual to checkpoint
+            if [ "${LOKI_FORCE_PERPETUAL:-false}" != "true" ] && [ "$AUTONOMY_MODE" = "perpetual" ]; then
+                AUTONOMY_MODE="checkpoint"
+                PERPETUAL_MODE="false"
+                log_info "Switched autonomy mode: perpetual -> checkpoint (PRD-driven work is finite)"
+            fi
+        fi
+    fi
+
     # Populate task queue from BMAD artifacts (if present, runs once)
     populate_bmad_queue
 
+    # Populate task queue from OpenSpec artifacts (if present, runs once)
+    populate_openspec_queue
+
     # Check max iterations before starting
     if check_max_iterations; then
         log_error "Max iterations already reached. Reset with: rm .loki/autonomy-state.json"
@@ -8302,29 +8553,54 @@ if __name__ == "__main__":
         # Checkpoint after each iteration (v5.57.0)
         create_checkpoint "iteration-${ITERATION_COUNT} complete" "iteration-${ITERATION_COUNT}"
 
-        # Quality gates (v6.7.0 - hard enforcement)
+        # Quality gates (v6.10.0 - escalation ladder)
         local gate_failures=""
         if [ "${LOKI_HARD_GATES:-true}" = "true" ]; then
             # Static analysis gate
             if [ "${PHASE_STATIC_ANALYSIS:-true}" = "true" ]; then
-                enforce_static_analysis || {
+                if enforce_static_analysis; then
+                    clear_gate_failure "static_analysis"
+                else
+                    local sa_count
+                    sa_count=$(track_gate_failure "static_analysis")
                     gate_failures="${gate_failures}static_analysis,"
-                    log_warn "Static analysis FAILED - findings injected into next iteration"
-                }
+                    log_warn "Static analysis FAILED ($sa_count consecutive) - findings injected into next iteration"
+                fi
             fi
             # Test coverage gate
             if [ "${PHASE_UNIT_TESTS:-true}" = "true" ]; then
-                enforce_test_coverage || {
+                if enforce_test_coverage; then
+                    clear_gate_failure "test_coverage"
+                else
+                    local tc_count
+                    tc_count=$(track_gate_failure "test_coverage")
                     gate_failures="${gate_failures}test_coverage,"
-                    log_warn "Test coverage gate FAILED - must pass next iteration"
-                }
+                    log_warn "Test coverage gate FAILED ($tc_count consecutive) - must pass next iteration"
+                fi
             fi
-            # Code review gate (upgraded from advisory)
+            # Code review gate (upgraded from advisory, with escalation)
             if [ "$PHASE_CODE_REVIEW" = "true" ] && [ "$ITERATION_COUNT" -gt 0 ]; then
-                run_code_review || {
-                    gate_failures="${gate_failures}code_review,"
-                    log_warn "Code review BLOCKED - Critical/High findings"
-                }
+                if run_code_review; then
+                    clear_gate_failure "code_review"
+                else
+                    local cr_count
+                    cr_count=$(track_gate_failure "code_review")
+                    if [ "$cr_count" -ge "$GATE_PAUSE_LIMIT" ]; then
+                        log_error "Gate escalation: code_review failed $cr_count times (>= $GATE_PAUSE_LIMIT) - forcing PAUSE for human intervention"
+                        echo "PAUSE" > "${TARGET_DIR:-.}/.loki/signals/GATE_ESCALATION"
+                        echo "code_review gate failed $cr_count consecutive times" >> "${TARGET_DIR:-.}/.loki/signals/GATE_ESCALATION"
+                        touch "${TARGET_DIR:-.}/.loki/signals/PAUSE"
+                    elif [ "$cr_count" -ge "$GATE_ESCALATE_LIMIT" ]; then
+                        log_warn "Gate escalation: code_review failed $cr_count times (>= $GATE_ESCALATE_LIMIT) - escalating"
+                        echo "ESCALATE" > "${TARGET_DIR:-.}/.loki/signals/GATE_ESCALATION"
+                        gate_failures="${gate_failures}code_review_ESCALATED,"
+                    elif [ "$cr_count" -ge "$GATE_CLEAR_LIMIT" ]; then
+                        log_warn "Gate cleared: code_review failed $cr_count times (>= $GATE_CLEAR_LIMIT) - passing gate this iteration, counter continues"
+                    else
+                        gate_failures="${gate_failures}code_review,"
+                        log_warn "Code review BLOCKED ($cr_count consecutive) - Critical/High findings"
+                    fi
+                fi
             fi
             # Store gate failures for prompt injection
             if [ -n "$gate_failures" ]; then

package/dashboard/__init__.py

@@ -7,7 +7,7 @@ Modules:
     control: Session control API (start/stop/pause/resume)
 """
 
-__version__ = "6.9.0"
+__version__ = "6.11.0"
 
 # Expose the control app for easy import
 try:

package/docs/INSTALLATION.md

@@ -2,7 +2,7 @@
 
 The flagship product of [Autonomi](https://www.autonomi.dev/). Complete installation instructions for all platforms and use cases.
 
-**Version:** v6.9.0
+**Version:** v6.11.0
 
 ---
 

package/mcp/__init__.py

@@ -57,4 +57,4 @@ try:
 except ImportError:
     __all__ = ['mcp']
 
-__version__ = '6.9.0'
+__version__ = '6.11.0'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loki-mode",
-  "version": "6.9.0",
+  "version": "6.11.0",
   "description": "Loki Mode by Autonomi - Multi-agent autonomous startup system for Claude Code, Codex CLI, and Gemini CLI",
   "keywords": [
     "agent",

package/skills/00-index.md

@@ -27,6 +27,7 @@
 | Scale patterns (50+ agents) | `parallel-workflows.md` + `references/cursor-learnings.md` |
 | GitHub issues, PRs, syncing | `github-integration.md` |
 | Multi-provider (Codex, Gemini) | `providers.md` |
+| OpenSpec delta context, brownfield modifications | `openspec-integration.md` |
 | Plan deepening, knowledge extraction | `compound-learning.md` |
 
 ## Module Descriptions
@@ -109,6 +110,14 @@
 - Filter by labels, milestone, assignee
 - Requires `gh` CLI authenticated
 
+### openspec-integration.md
+**When:** Working with OpenSpec delta context, `--openspec` flag, brownfield modifications
+- Delta-aware development rules (ADDED/MODIFIED/REMOVED)
+- Task execution by group order
+- Scenario-to-test mapping (GIVEN/WHEN/THEN)
+- Source mapping and verification tracking
+- Complexity-based agent strategy
+
 ### compound-learning.md (v5.30.0)
 **When:** After architecture phase (deepen plan), after verification (extract learnings)
 - Deepen-plan: 4 parallel research agents enhance plans before implementation

package/skills/openspec-integration.md

@@ -0,0 +1,147 @@
+# OpenSpec Integration
+
+> **Reference:** OpenSpec delta specs use ADDED/MODIFIED/REMOVED sections to describe changes to existing system behavior. See `.loki/openspec/delta-context.json` for the parsed delta context injected into your prompt.
+
+---
+
+## When This Module Applies
+
+- Your prompt contains an `OPENSPEC DELTA CONTEXT` section
+- The project has `.loki/openspec/delta-context.json`
+- The session was started with `--openspec` flag
+- Tasks in `.loki/queue/pending.json` have `openspec_group` metadata
+
+**If none of the above are true, do not load this module.**
+
+---
+
+## Delta-Aware Development Rules
+
+### ADDED Requirements
+
+New behavior that does not exist in the codebase yet.
+
+1. Create NEW files and functions following existing codebase patterns
+2. Do NOT modify existing code unless the new feature integrates with it
+3. Write tests for every scenario (GIVEN/WHEN/THEN from the delta spec)
+4. Reference: `delta-context.json` entries with `"type": "added"`
+
+```
+# Mental model for ADDED
+Read scenario -> Write test -> Implement -> Verify test passes
+```
+
+### MODIFIED Requirements
+
+Existing behavior that is changing. This is the most common delta type in brownfield work.
+
+1. Find the EXISTING code that implements this requirement
+2. Modify IN PLACE -- do NOT create new files for modified behavior
+3. Check the `(Previously: ...)` annotation to understand what changed
+4. Update existing tests to match the new behavior
+5. Reference: `delta-context.json` entries with `"type": "modified"`
+
+```
+# Mental model for MODIFIED
+Read "(Previously: ...)" -> Find existing code -> Update code -> Update tests -> Verify
+```
+
+**Common mistake:** Treating MODIFIED as ADDED and creating new files. Always search the codebase first for the existing implementation.
+
+### REMOVED Requirements
+
+Behavior that is being deprecated or deleted.
+
+1. Find and remove or deprecate the code implementing this requirement
+2. Check the `(Deprecated: ...)` annotation for the reason
+3. Remove associated tests
+4. Ensure no orphaned imports or dead code remains
+5. Reference: `delta-context.json` entries with `"type": "removed"`
+
+```
+# Mental model for REMOVED
+Read "(Deprecated: ...)" -> Find existing code -> Remove code -> Remove tests -> Verify no dead refs
+```
+
+---
+
+## Task Execution
+
+Tasks are generated from OpenSpec `tasks.md` and loaded into `.loki/queue/pending.json`.
+
+- Each task has `openspec_group` metadata indicating its task group number
+- Execute tasks in group order (group 1 before group 2, etc.)
+- Within a group, tasks can run in parallel if they touch different files
+- Mark tasks complete in the queue when done
+
+```json
+{
+  "id": "task-3",
+  "title": "Implement session timeout change",
+  "openspec_group": 1,
+  "delta_type": "modified",
+  "spec_ref": "auth/spec.md#session-expiration"
+}
+```
+
+---
+
+## Scenario Verification
+
+After implementing a requirement, verify its scenarios.
+
+1. Each scenario has GIVEN (precondition), WHEN (action), THEN (expected outcome)
+2. Write test cases that map 1:1 to scenarios
+3. Use the scenario name as the test name for traceability
+4. Verification results are tracked in `.loki/openspec/verification-results.json`
+
+```python
+# Scenario: "Idle timeout" -> test name matches scenario
+def test_idle_timeout():
+    # GIVEN an authenticated session
+    session = create_authenticated_session()
+    # WHEN 15 minutes pass without activity
+    advance_time(minutes=15)
+    # THEN the session is invalidated
+    assert session.is_expired()
+```
+
+---
+
+## Source Mapping
+
+`.loki/openspec/source-map.json` maps each task ID to its origin in the spec files.
+
+| Field | Purpose |
+|-------|---------|
+| `task_id` | Queue task identifier |
+| `spec_file` | Source spec file path |
+| `requirement` | Requirement name |
+| `scenario` | Scenario name (if applicable) |
+| `line` | Line number in spec file |
+
+Use this to trace implementation decisions back to the specification.
+
+---
+
+## Complexity Levels
+
+| Level | Tasks | Spec Files | Design | Agent Strategy |
+|-------|-------|------------|--------|----------------|
+| simple | 1-3 | 1 | none | Single agent, sequential |
+| standard | 4-10 | 2-5 | present | Parallel where possible |
+| complex | 11-20 | 5-10 | present | Task tool parallelization |
+| enterprise | 20+ | 10+ | present | Full agent team |
+
+---
+
+## Common Mistakes
+
+| Mistake | Correction |
+|---------|------------|
+| Creating new files for MODIFIED requirements | Search codebase first, update existing code in place |
+| Ignoring `(Previously: ...)` annotations | These tell you exactly what changed -- read them |
+| Not writing tests for GIVEN/WHEN/THEN scenarios | Every scenario must have a corresponding test |
+| Treating all deltas as ADDED | Most brownfield work is MODIFIED -- check the delta type |
+| Skipping REMOVED cleanup | Dead code and orphaned imports cause maintenance burden |
+| Implementing groups out of order | Group 1 must complete before group 2 starts |