RUNBOOK.yaml

schema_version: '1.0'
lock:
  active_claim: null
  claimed_by: null
  claimed_at: '2026-04-07T01:20:00Z'
review:
  max_rounds: 3
  required_gates:
  - eight_eyes
  - collab
  merge_policy: human_approval
  rollback_on_max_rounds: true
completed_phases:
- id: P0
  name: "Phase 0 \xE2\u20AC\u201D Emergency Hardening"
  epics: 11
  pr_range: "#433\xE2\u20AC\u201C#467"
- id: P1
  name: "Phase 1 \xE2\u20AC\u201D Foundation Architecture"
  epics: 8
  pr_range: "#451\xE2\u20AC\u201C#459"
- id: P2
  name: "Phase 2 \xE2\u20AC\u201D Smart Sandbox"
  epics: 6
  pr_range: '#1'
- id: P3
  name: "Phase 3 \xE2\u20AC\u201D Skill Store Decomposition"
  epics: 7
  pr_range: "#12\xE2\u20AC\u201C#28"
  notes: 'Monolithic store.py (1,345 lines) decomposed into 5 focused modules (SkillRepository,
    LineageTracker, AnalysisStore, TagSearch, MigrationManager) plus types.py. 7 epics
    + 3 validation/cleanup PRs. 1,356 tests passing.

    '
- id: P4
  name: "Phase 4 \xE2\u20AC\u201D Tool Layer + MCP Decomposition"
  epics: 10
  pr_range: "#31\xE2\u20AC\u201C#38"
  notes: 'tool_layer.py (788 lines) decomposed into 4 focused modules (ToolRegistry,
    ExecutionEngine, RecordingService, LLMFactory) + facade cleanup. mcp_server.py
    (992 lines) decomposed into openspace/mcp/ package (server.py, tool_handlers.py)
    + backward-compat shim. 2 epics skipped (4.2 covered by 4.1, 4.8 covered by P3).
    62 new tests. 1,408 passing.

    '
active_phase:
  id: P5
  name: "Phase 5 \xE2\u20AC\u201D Skill Engine / Grounding Decomposition"
  status: in_progress
  epics_total: 11
  epics_merged: 0
epics:
- id: '2.6'
  phase: P2
  title: Secret Broker
  status: merged
  branch: epic/2.6-secret-broker
  pr: 1
  review_round: 5
  description: 'Scoped storage, encryption at rest, capability-based access with owner
    isolation. 64 tests, 1028 suite passing.

    '
  acceptance:
  - SecretBroker passes all 64 unit tests
  - Owner isolation enforced across get/revoke/list/put
  - Full suite 1028+ green
  - /8eyes + /collab buyoff
- id: '3.1'
  phase: P3
  title: Extract SkillSchema + SkillVersion models
  status: merged
  branch: epic/3.1-skill-schema
  pr: 12
  review_round: 2
  source_file: openspace/skill_engine/store.py
  target_module: openspace/skill_engine/skill_schema.py
  description: 'Extract SkillSchema and SkillVersion frozen dataclasses/models from
    store.py. These are the core domain types for the skill persistence layer.

    '
  acceptance:
  - skill_schema.py contains all model definitions
  - store.py imports from skill_schema.py
  - All existing tests pass unchanged
- id: '3.2'
  phase: P3
  title: Extract SkillRepository (CRUD)
  status: merged
  branch: epic/3.2-skill-repository
  pr: 15
  review_round: 2
  source_file: openspace/skill_engine/store.py
  target_module: openspace/skill_engine/skill_repository.py
  description: 'Extract save_record, load_record, load_all, load_active, delete_record,
    deactivate/reactivate and all sync variants into a focused repository class.

    '
  acceptance:
  - skill_repository.py handles all CRUD operations
  - store.py delegates to SkillRepository
  - All existing tests pass unchanged
- id: '3.3'
  phase: P3
  title: Extract LineageTracker
  status: merged
  branch: epic/3.3-lineage-tracker
  pr: 17
  review_round: 2
  source_file: openspace/skill_engine/store.py
  target_module: openspace/skill_engine/lineage_tracker.py
  description: 'Extract get_ancestry, get_lineage_tree, _subtree, find_children, evolve_skill
    into a focused lineage/derivation graph module.

    '
  acceptance:
  - lineage_tracker.py owns all parent-child and derivation graph logic
  - All existing tests pass unchanged
- id: '3.4'
  phase: P3
  title: Extract AnalysisStore
  status: merged
  branch: epic/3.4-analysis-store
  pr: 19
  review_round: 2
  source_file: openspace/skill_engine/store.py
  target_module: openspace/skill_engine/analysis_store.py
  description: 'Extract record_analysis, load_analyses, load_analyses_for_task, load_all_analyses,
    load_evolution_candidates, _insert_analysis into a focused analysis persistence
    module.

    '
  acceptance:
  - analysis_store.py owns quality scores and evolution trigger data
  - All existing tests pass unchanged
- id: '3.5'
  phase: P3
  title: Extract TagIndex + SearchEngine
  status: merged
  branch: epic/3.5-tag-search
  pr: 21
  review_round: 2
  source_file: openspace/skill_engine/store.py
  target_module: openspace/skill_engine/tag_index_search.py
  description: 'Extract find_skills_by_tool, load_by_category, get_summary, get_stats,
    get_top_skills, get_task_skill_summary, count into search/analytics module.

    '
  acceptance:
  - tag_index_search.py owns all query and analytics operations
  - All existing tests pass unchanged
- id: '3.6'
  phase: P3
  title: Extract MigrationManager
  status: merged
  branch: epic/3.6-migration-manager
  pr: 23
  review_round: 2
  source_file: openspace/skill_engine/store.py
  target_module: openspace/skill_engine/migration_manager.py
  description: 'Extract _init_db, _make_connection, _cleanup_wal_on_startup, _ensure_open,
    _db_retry, vacuum, clear into a DB lifecycle and schema migration module.

    '
  acceptance:
  - migration_manager.py owns DDL, WAL recovery, and connection lifecycle
  - All existing tests pass unchanged
- id: '3.7'
  phase: P3
  title: P3 integration tests + store.py cleanup
  status: merged
  branch: epic/3.7-integration-cleanup
  pr: 25
  review_round: 4
  notes: 'Additional PRs: #26 (E2E validation, 7 blockers fixed), #27 (warning cleanup),
    #28 (batch hydration + mypy fixes). All merged. 1,356 tests passing.

    '
  source_file: openspace/skill_engine/store.py
  target_module: null
  description: 'Final integration epic: verify all 7 modules work together, add backward
    compatibility tests, then replace store.py with a thin re-export facade or delete
    entirely.

    '
  acceptance:
  - store.py is either deleted or reduced to re-export facade
  - All 7 extracted modules have dedicated tests
  - Full suite passes (1028+ tests)
  - /8eyes + /collab buyoff on complete P3
- id: '4.1'
  phase: P4
  title: Extract ToolRegistry
  status: merged
  branch: epic/4.1-tool-registry
  pr: 31
  review_round: 2
  source_file: openspace/tool_layer.py
  target_module: openspace/tool_registry.py
  description: 'Extract tool registration, discovery, and backend listing from OpenSpace
    class.

    '
  acceptance:
  - tool_registry.py manages tool lifecycle independently
  - All existing tests pass unchanged
- id: '4.2'
  phase: P4
  title: Extract SkillSelector
  status: skipped
  branch: null
  pr: null
  review_round: 0
  source_file: openspace/tool_layer.py
  target_module: openspace/skill_selector.py
  description: 'Extract _select_and_inject_skills, _get_skill_selection_llm into focused
    skill-first routing module.

    '
  acceptance:
  - "skill_selector.py owns the skill-first \xE2\u2020\u2019 fallback decision"
  - All existing tests pass unchanged
- id: '4.3'
  phase: P4
  title: Extract ExecutionEngine
  status: merged
  branch: epic/4.3-execution-engine
  pr: 32
  review_round: 2
  source_file: openspace/tool_layer.py
  target_module: openspace/execution_engine.py
  description: 'Extract execute method and fallback orchestration logic.

    '
  acceptance:
  - execution_engine.py handles task execution with skill injection
  - All existing tests pass unchanged
- id: '4.4'
  phase: P4
  title: Extract RecordingService
  status: merged
  branch: epic/4.4-recording-service
  pr: 33
  review_round: 1
  source_file: openspace/tool_layer.py
  target_module: openspace/recording_service.py
  description: 'Extract _maybe_analyze_execution, _maybe_evolve_quality and all trace
    capture/recording logic.

    '
  acceptance:
  - recording_service.py owns execution trace capture
  - All existing tests pass unchanged
- id: '4.5'
  phase: P4
  title: Extract LLMAdapter
  status: merged
  branch: epic/4.5-llm-factory
  pr: 34
  review_round: 1
  source_file: openspace/tool_layer.py
  target_module: openspace/llm_adapter.py
  description: 'Extract LLM client initialization and provider abstraction.

    '
  acceptance:
  - llm_adapter.py provides a clean provider-agnostic LLM interface
  - All existing tests pass unchanged
- id: '4.6'
  phase: P4
  title: Extract ToolLayerFacade
  status: merged
  branch: epic/4.6-facade-cleanup
  pr: 35
  review_round: 2
  source_file: openspace/tool_layer.py
  target_module: openspace/tool_layer_facade.py
  description: 'Reduce tool_layer.py to thin facade that composes the 5 extracted
    modules. Preserve public API (OpenSpace class, OpenSpaceConfig).

    '
  acceptance:
  - tool_layer.py is a thin re-export facade or deleted
  - Public API unchanged
  - All existing tests pass unchanged
- id: '4.7'
  phase: P4
  title: Extract MCPToolHandlers
  status: merged
  branch: epic/4.7-mcp-tool-handlers
  pr: 36
  review_round: 2
  source_file: openspace/mcp_server.py
  target_module: openspace/mcp/tool_handlers.py
  description: 'Extract execute_task, search_skills, fix_skill, upload_skill handlers
    and their helpers into focused handler module.

    '
  acceptance:
  - tool_handlers.py contains all 4 MCP tool implementations
  - All existing tests pass unchanged
- id: '4.8'
  phase: P4
  title: Extract MCPAuthMiddleware
  status: skipped
  branch: null
  pr: null
  review_round: 0
  source_file: openspace/mcp_server.py
  target_module: openspace/mcp/auth_middleware.py
  description: 'Extract RateLimitMiddleware, BearerTokenMiddleware, and HMAC auth
    into dedicated auth middleware module.

    '
  acceptance:
  - auth_middleware.py owns all MCP authentication/authorization
  - All existing tests pass unchanged
- id: '4.9'
  phase: P4
  title: Extract MCPRouter + MCPServer
  status: merged
  branch: epic/4.9-mcp-server-extract
  pr: 37
  review_round: 2
  source_file: openspace/mcp_server.py
  target_module: openspace/mcp/server.py
  description: 'Extract endpoint wiring (MCPRouter) and server lifecycle (run_mcp_server)
    into clean server module. Create openspace/mcp/ package.

    '
  acceptance:
  - openspace/mcp/ package exists with clean separation
  - mcp_server.py is thin facade or deleted
  - All existing tests pass unchanged
- id: '4.10'
  phase: P4
  title: P4 integration tests + MCP conformance
  status: merged
  branch: epic/4.10-integration-tests
  pr: 38
  review_round: 2
  source_file: null
  target_module: tests/test_mcp_conformance.py
  description: 'Integration tests verifying tool_layer and MCP server modules work
    together. MCP protocol conformance test harness.

    '
  acceptance:
  - Full suite passes (1028+ tests)
  - MCP protocol conformance tests pass
  - /8eyes + /collab buyoff on complete P4
- id: '5.1'
  phase: P5
  title: Extract EvolutionModels
  status: done
  branch: null
  pr: 39
  review_round: 0
  source_file: openspace/skill_engine/evolver.py
  target_module: openspace/skill_engine/evolution/models.py
  description: 'Extract EvolutionTrigger, EvolutionContext, _sanitize_skill_name into
    domain models module.

    '
  acceptance:
  - models.py contains all evolution domain types
  - All existing tests pass unchanged
- id: '5.2'
  phase: P5
  title: Extract EvolutionOrchestrator
  status: done
  branch: null
  pr: 40
  review_round: 0
  source_file: openspace/skill_engine/evolver.py
  target_module: openspace/skill_engine/evolution/orchestrator.py
  description: 'Extract evolve, _execute_contexts, schedule_background, _log_background_result
    into orchestration module.

    '
  acceptance:
  - orchestrator.py owns evolution scheduling and dispatch
  - All existing tests pass unchanged
- id: '5.3'
  phase: P5
  title: Extract AnalysisEvolution + ToolDegradation + MetricMonitor
  status: done
  branch: null
  pr: 41
  review_round: 0
  source_file: openspace/skill_engine/evolver.py
  target_module: openspace/skill_engine/evolution/triggers/
  description: 'Extract process_analysis, process_tool_degradation, process_metric_check
    into three focused trigger modules.

    '
  acceptance:
  - Each trigger type has its own module
  - All existing tests pass unchanged
- id: '5.4'
  phase: P5
  title: Extract EvolutionConfirmation
  status: done
  branch: null
  pr: 42
  review_round: 0
  source_file: openspace/skill_engine/evolver.py
  target_module: openspace/skill_engine/evolution/confirmation.py
  description: 'Extract _llm_confirm_evolution, _parse_confirmation into LLM confirmation/approval
    module.

    '
  acceptance:
  - confirmation.py owns the LLM-based evolution approval flow
  - All existing tests pass unchanged
- id: '5.5'
  phase: P5
  title: Extract FixEngine + DerivedCapturedEngine
  status: done
  branch: null
  pr: 43
  review_round: 0
  source_file: openspace/skill_engine/evolver.py
  target_module: openspace/skill_engine/evolution/engines/
  description: 'Extract _evolve_fix, _evolve_derived, _evolve_captured, _run_evolution_loop,
    _parse_evolution_output, _apply_with_retry into evolution engine modules.

    '
  acceptance:
  - FIX, DERIVED, CAPTURED each have focused engine modules
  - All existing tests pass unchanged
- id: '5.6'
  phase: P5
  title: "P5a integration \xE2\u20AC\u201D evolver.py deletion"
  status: done
  branch: null
  pr: 44
  review_round: 0
  source_file: openspace/skill_engine/evolver.py
  target_module: null
  description: 'Replace evolver.py with thin facade or delete. Verify all 9 evolution
    modules integrate correctly.

    '
  acceptance:
  - evolver.py is facade or deleted
  - openspace/skill_engine/evolution/ package complete
  - All existing tests pass
- id: '5.7'
  phase: P5
  title: Extract SkillContextManager + MessageSafety
  status: done
  branch: null
  pr: 45
  review_round: 0
  source_file: openspace/agents/grounding_agent.py
  target_module: openspace/agents/grounding/
  description: 'Extract set_skill_context, clear_skill_context, _cap_message_content,
    _truncate_messages into focused modules.

    '
  acceptance:
  - Skill context and message safety are independent modules
  - All existing tests pass unchanged
- id: '5.8'
  phase: P5
  title: Extract AgentExecutionLoop + PromptBuilder
  status: done
  branch: null
  pr: 46
  review_round: 0
  source_file: openspace/agents/grounding_agent.py
  target_module: openspace/agents/grounding/
  description: 'Extract process (core loop), construct_messages, _default_system_prompt
    into execution loop and prompt builder modules.

    '
  acceptance:
  - Core reasoning loop is independent of tool/visual/workspace concerns
  - All existing tests pass unchanged
- id: '5.9'
  phase: P5
  title: Extract ToolCatalog + VisualAnalysis + WorkspaceInspector
  status: done
  branch: null
  pr: 47
  review_round: 0
  source_file: openspace/agents/grounding_agent.py
  target_module: openspace/agents/grounding/
  description: 'Extract _get_available_tools, _load_all_tools, _visual_analysis_callback,
    _scan_workspace_files, _check_workspace_artifacts into focused modules.

    '
  acceptance:
  - Tool discovery, visual analysis, and workspace scanning are independent
  - All existing tests pass unchanged
- id: '5.10'
  phase: P5
  title: Extract ResultFormatter + Telemetry
  status: done
  branch: null
  pr: 48
  review_round: 0
  source_file: openspace/agents/grounding_agent.py
  target_module: openspace/agents/grounding/result_telemetry.py
  description: 'Extract _build_final_result, _format_tool_executions, _generate_final_summary,
    _record_agent_execution into result formatting and telemetry module.

    '
  acceptance:
  - Result formatting and execution recording are independent
  - All existing tests pass unchanged
- id: '5.11'
  phase: P5
  title: "P5b integration \xE2\u20AC\u201D grounding_agent.py deletion"
  status: done
  branch: null
  pr: 49
  review_round: 0
  source_file: openspace/agents/grounding_agent.py
  target_module: null
  description: 'Replace grounding_agent.py with thin facade or delete. Verify all
    8 grounding modules integrate correctly. Full /8eyes + /collab on P5.

    '
  acceptance:
  - grounding_agent.py is facade or deleted
  - openspace/agents/grounding/ package complete
  - Full suite passes (1028+ tests)
  - /8eyes + /collab buyoff on complete P5
- id: '6.1'
  phase: P6
  title: Observability (metrics, tracing, health)
  status: done
  branch: epic/6.1-observability
  pr: 50
  review_round: 2
  description: 'Add structured metrics (execution latency, skill hit rate, evolution
    success rate), distributed tracing for multi-step workflows, and health check
    endpoints for MCP server.

    '
  acceptance:
  - Prometheus-compatible metrics endpoint
  - Health check endpoint returns structured status
  - Execution traces captured for debugging
- id: '6.2'
  phase: P6
  title: SLOs (latency, error rate, availability)
  status: done
  branch: epic/6.2-slos
  pr: 51
  review_round: 2
  description: 'Define and enforce SLO targets: p99 execution latency, error rate
    budget, availability targets. Add SLO burn-rate alerting logic.

    '
  acceptance:
  - SLO targets documented and measurable
  - Burn-rate calculations implemented
  - Tests for SLO boundary conditions
- id: '6.3'
  phase: P6
  title: Deployment architecture
  status: done
  branch: epic/6.3-deployment
  pr: 52
  review_round: 2
  description: 'Containerization (Dockerfile), config management (env-based), graceful
    shutdown, startup probes, resource limits.

    '
  acceptance:
  - Dockerfile builds and runs successfully
  - Config via environment variables documented
  - Graceful shutdown handles in-flight tasks
  notes:
  - DeployConfig frozen dataclass with env-based config
  - GracefulShutdownHandler with global monotonic deadline, 70/30 drain/hook budget
  - /health endpoint outside auth for K8s probes
  - HEALTHCHECK hits real /health endpoint
  - Dockerfile multi-stage, non-root, OPENSPACE_SHUTDOWN_TIMEOUT=8
  - 41 deployment tests, 1925 total passed
  - 2 review rounds, 9 agents total
- id: '6.4'
  phase: P6
  title: DX polish (CLI help, errors, onboarding)
  status: done
  branch: epic/6.4-dx-polish
  pr: 53
  review_round: 2
  description: 'Improve CLI help text, error messages with actionable suggestions,
    first-run onboarding flow, quickstart documentation.

    '
  acceptance:
  - Every CLI command has --help with examples
  - Error messages include suggested fixes
  - Quickstart guide tested on clean install
  - /8eyes + /collab buyoff on complete P6
  notes:
  - Rich --help with epilog (examples, env vars, auth notes), --version
  - Preflight checks: bearer token, skill store, port, Python version
  - Platform-aware suggestions (PowerShell on Win, bash on Unix)
  - Output writes to sys.__stderr__ (console), not just logger (file)
  - 32 DX tests, 1957 total passed
  - 2 review rounds, 7 agents total (4 R1 + 3 R2)
- id: '7.1'
  phase: P7
  title: Eight-eyes integration
  status: done
  branch: epic/7.1-review-gate
  pr: 54
  review_round: 3
  description: "Built-in /8eyes review for skill evolution \xE2\u20AC\u201D every\
    \ evolved skill gets multi-agent review before activation.\n"
  acceptance:
  - Skill evolution triggers /8eyes review automatically
  - Evolved skills quarantined until review passes
  notes: |
    ReviewGate with 5-layer security: path traversal, extension allowlist,
    size limits, HIGH+CRITICAL AST blocking, lineage.validate().
    63 tests (45 adversarial), 2020 total passed.
    3 review rounds, 12 agent-reviews (impl, sec, GPT-5.4, Opus 4.6).
- id: '7.2'
  phase: P7
  title: SkillGuard quality gates
  status: pending
  branch: null
  pr: null
  review_round: 0
  description: 'Automated skill quality gates: blocklist enforcement, capability scope
    validation, test coverage minimums for activated skills.

    '
  acceptance:
  - SkillGuard blocks activation of unsafe skills
  - Capability scope validated against tier
  - Test coverage minimum enforced
- id: '7.3'
  phase: P7
  title: Launch checklist
  status: pending
  branch: null
  pr: null
  review_round: 0
  description: 'Final security audit, documentation completeness, release notes, changelog,
    license verification, dependency audit clean.

    '
  acceptance:
  - Security audit report clean
  - All docs up to date
  - CHANGELOG.md covers all phases
  - pip-audit clean (zero known vulnerabilities)
  - /8eyes + /collab buyoff on complete P7
  - PROJECT COMPLETE