ouroboros-ai 0.26.7.dev2__tar.gz → 0.26.7.dev4__tar.gz

{ouroboros_ai-0.26.7.dev2 → ouroboros_ai-0.26.7.dev4}/CLAUDE.md

@@ -31,6 +31,7 @@ When the user types any of these commands, read the corresponding SKILL.md file
 | `ooo update` | Read `skills/update/SKILL.md` and follow it |
 | `ooo pm` or `ooo pm ...` | Read `skills/pm/SKILL.md` and follow it |
 | `ooo brownfield` or `ooo brownfield ...` | Read `skills/brownfield/SKILL.md` and follow it |
+| `ooo publish` or `ooo publish ...` | Read `skills/publish/SKILL.md` and follow it |
 
 **Important**: Do NOT use the Skill tool. Read the file with the Read tool and execute its instructions directly.
 
@@ -79,6 +80,7 @@ Each command loads its agent/MCP on-demand. Details in each skill file.
 | `ooo setup` | — |
 | `ooo help` | — |
 | `ooo update` | PyPI version check + upgrade |
+| `ooo publish` | `gh` CLI — Seed to GitHub Issues |
 
 ## Agents
 

{ouroboros_ai-0.26.7.dev2 → ouroboros_ai-0.26.7.dev4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ouroboros-ai
-Version: 0.26.7.dev2
+Version: 0.26.7.dev4
 Summary: Specification-first workflow engine for AI coding agents. Works with Claude Code and Codex CLI.
 Author-email: Q00 <jqyu.lee@gmail.com>
 License-File: LICENSE

{ouroboros_ai-0.26.7.dev2 → ouroboros_ai-0.26.7.dev4}/skills/help/SKILL.md

@@ -46,6 +46,7 @@ Ouroboros is a **requirement crystallization engine** for AI workflows. It trans
 | `ooo cancel` | Cancel stuck or orphaned executions | CLI |
 | `ooo update` | Check for updates + upgrade to latest | Plugin |
 | `ooo brownfield` | Scan and manage brownfield repo defaults | MCP |
+| `ooo publish` | Publish Seed as GitHub Issues for teams | Plugin |
 
 ### Evolutionary Loop
 
@@ -77,6 +78,7 @@ Ouroboros is a **requirement crystallization engine** for AI workflows. It trans
 | "cancel execution", "stop job", "kill stuck", "abort execution" | `ooo cancel` |
 | "update ouroboros", "upgrade ouroboros" | `ooo update` |
 | "brownfield defaults", "brownfield scan" | `ooo brownfield` |
+| "publish to github", "create issues from seed", "seed to issues" | `ooo publish` |
 
 ### Loop Triggers
 
@@ -106,6 +108,7 @@ Ouroboros is a **requirement crystallization engine** for AI workflows. It trans
 | `/ouroboros:cancel` | Cancel stuck or orphaned executions | CLI |
 | `/ouroboros:update` | Check for updates + upgrade to latest | Plugin |
 | `/ouroboros:brownfield` | Scan and manage brownfield repo defaults | MCP |
+| `/ouroboros:publish` | Publish Seed as GitHub Issues for teams | Plugin |
 
 ### Loop Skills
 

ouroboros_ai-0.26.7.dev4/skills/publish/SKILL.md

@@ -0,0 +1,355 @@
+---
+name: publish
+description: "Publish Seed specification as GitHub Issues for team-based project management"
+---
+
+# /ouroboros:publish
+
+Convert a Seed specification into structured GitHub Issues for team workflows.
+
+## Usage
+
+```
+ooo publish [seed_path]
+/ouroboros:publish [seed_path]
+```
+
+**Trigger keywords:** "publish to github", "create issues from seed", "seed to issues"
+
+## Instructions
+
+When the user invokes this skill:
+
+### Step 1: Prerequisite Check
+
+**1a. Verify `gh` CLI is installed:**
+
+```bash
+command -v gh >/dev/null 2>&1 && echo "OK" || echo "MISSING"
+```
+
+If missing, tell the user:
+```
+GitHub CLI (gh) is not installed.
+Install it: https://cli.github.com/
+```
+Stop.
+
+**1b. Verify `gh` is authenticated:**
+
+```bash
+gh auth status
+```
+
+If not authenticated, tell the user:
+```
+GitHub CLI is not authenticated. Run: gh auth login
+```
+Stop.
+
+### Step 2: Locate the Seed
+
+Ouroboros stores seeds in `~/.ouroboros/seeds/`:
+- **Interview seeds**: `~/.ouroboros/seeds/{seed_id}.yaml` (YAML)
+- **PM seeds**: `~/.ouroboros/seeds/pm_seed_{id}.json` (JSON)
+
+Determine the Seed source in this priority order:
+
+1. **Explicit path argument**: If the user provided a file path (`.yaml` or `.json`), read it directly
+2. **Most recent seed file**: Search for the most recent seed in the standard location:
+   ```bash
+   ls -t ~/.ouroboros/seeds/*.yaml ~/.ouroboros/seeds/*.json 2>/dev/null | head -5
+   ```
+   If multiple seeds exist, present the top candidates via AskUserQuestion and let the user choose.
+3. **Conversation context**: If `ooo seed` or `ooo pm` was just run in this conversation and the seed path was reported, use that path.
+
+If no seed is found:
+```
+No Seed found. Run `ooo seed` or `ooo pm` first to generate a specification.
+```
+Stop.
+
+### Step 3: Parse the Seed
+
+Detect the file format by extension and parse accordingly:
+
+**For YAML seeds** (from `ooo interview` + `ooo seed`):
+Read the YAML file and extract:
+- `goal` → Epic title and description
+- `constraints` → Listed in Epic body
+- `acceptance_criteria` → Checklist items in Epic + distributed to Task issues
+- `ontology_schema` → Documentation section in Epic
+- `evaluation_principles` → Quality criteria reference
+- `exit_conditions` → Definition of Done
+- `metadata.ambiguity_score` → Confidence indicator
+- `metadata.seed_id` → Used for duplicate detection
+
+**For JSON seeds** (from `ooo pm`):
+Read the JSON file and extract fields using the actual `PMSeed` schema:
+
+| PMSeed field | Maps to |
+|-------------|---------|
+| `pm_id` | Seed identifier (for duplicate detection) |
+| `product_name` | Epic title prefix |
+| `goal` | Epic Goal section |
+| `constraints` | Epic Constraints section (array of strings) |
+| `success_criteria` | Acceptance Criteria checklist (array of strings) |
+| `user_stories` | User Stories section (array of `{persona, action, benefit}`) |
+| `deferred_items` | Deferred Items section (array of strings) |
+| `decide_later_items` | Open Questions section (array of strings) |
+| `assumptions` | Assumptions section (array of strings) |
+
+Format user stories as: "As a **{persona}**, I want to **{action}**, so that **{benefit}**."
+
+If any field is missing or empty, omit that section from the Epic body rather than failing.
+
+### Step 4: Detect Repository
+
+**4a. Attempt auto-detection from current directory:**
+
+```bash
+gh repo view --json nameWithOwner -q '.nameWithOwner' 2>/dev/null
+```
+
+**4b. Present the target repo choice via AskUserQuestion:**
+
+If auto-detection succeeded:
+```json
+{
+  "questions": [{
+    "question": "Publish Seed as GitHub Issues to this repository?",
+    "header": "Target Repository",
+    "options": [
+      {"label": "<detected_repo>", "description": "Use current repository"},
+      {"label": "Other", "description": "I'll specify a different owner/repo"}
+    ],
+    "multiSelect": false
+  }]
+}
+```
+
+If auto-detection failed (not in a git repo):
+```json
+{
+  "questions": [{
+    "question": "Which GitHub repository should the issues be created in? (format: owner/repo)",
+    "header": "Target Repository"
+  }]
+}
+```
+
+If the user chose "Other", ask:
+```json
+{
+  "questions": [{
+    "question": "Enter the target repository (format: owner/repo):",
+    "header": "Target Repository"
+  }]
+}
+```
+
+Store the resolved repository as `TARGET_REPO`. **All subsequent `gh` commands MUST include `-R <TARGET_REPO>`** to ensure they target the correct repository.
+
+### Step 5: Duplicate Check
+
+Before creating issues, check if this seed was already published:
+
+```bash
+gh issue list -R <TARGET_REPO> --label "ouroboros" --state all --search "<seed_id or pm_id>" --limit 5 --json number,title,state
+```
+
+The search uses the seed's unique identifier (`metadata.seed_id` for YAML seeds, `pm_id` for JSON seeds). This works because Step 7 persists the identifier in the Epic body (see the `Seed ID` field in the Epic template).
+
+If matching issues are found, warn the user via AskUserQuestion:
+```json
+{
+  "questions": [{
+    "question": "Found existing Ouroboros issues that may be from the same seed:\n\n<list of matching issues>\n\nCreate new issues anyway?",
+    "header": "Duplicate Warning",
+    "options": [
+      {"label": "Create anyway", "description": "Proceed with new issues"},
+      {"label": "Cancel", "description": "Do not create duplicate issues"}
+    ],
+    "multiSelect": false
+  }]
+}
+```
+
+If "Cancel": Stop.
+
+### Step 6: Plan Issue Structure
+
+Before creating issues, present the planned structure to the user for review.
+
+**6a. Break down acceptance criteria into Task groups:**
+
+Analyze the acceptance criteria and group them into logical implementation units. Each unit becomes a Task issue. Use your understanding of the domain to create meaningful groupings (e.g., group by feature area, layer, or dependency order).
+
+**6b. Present the plan via AskUserQuestion:**
+
+```json
+{
+  "questions": [{
+    "question": "Here's the planned issue structure:\n\n**Epic**: <goal summary>\n\n**Tasks**:\n1. <task_1_title> — <brief scope>\n2. <task_2_title> — <brief scope>\n3. <task_3_title> — <brief scope>\n\nProceed with creating these issues?",
+    "header": "Issue Plan",
+    "options": [
+      {"label": "Create issues", "description": "Publish to GitHub now"},
+      {"label": "Modify plan", "description": "I want to adjust the structure first"}
+    ],
+    "multiSelect": false
+  }]
+}
+```
+
+If "Modify plan": Ask what to change, adjust, and re-present.
+
+### Step 7: Create GitHub Issues
+
+**IMPORTANT**: Every `gh` command in this step MUST include `-R <TARGET_REPO>`.
+
+**Issue number extraction**: `gh issue create` outputs a URL like `https://github.com/owner/repo/issues/42`. Extract the issue number by parsing the trailing digits:
+```bash
+EPIC_URL=$(gh issue create -R <TARGET_REPO> --title "..." --label "..." --body "...")
+EPIC_NUM=$(echo "$EPIC_URL" | grep -o '[0-9]*$')
+```
+Apply the same extraction pattern for every Task issue created.
+
+**7a. Create labels (if they don't exist):**
+
+```bash
+gh label create "ouroboros" -R <TARGET_REPO> --description "Created by Ouroboros publish" --color "6f42c1" 2>/dev/null || true
+gh label create "epic" -R <TARGET_REPO> --description "Epic / parent issue" --color "0075ca" 2>/dev/null || true
+gh label create "task" -R <TARGET_REPO> --description "Implementation task" --color "008672" 2>/dev/null || true
+```
+
+**7b. Create the Epic issue:**
+
+```bash
+gh issue create -R <TARGET_REPO> \
+  --title "[Epic] <goal_summary>" \
+  --label "ouroboros,epic" \
+  --body "$(cat <<'BODY'
+## Goal
+
+<goal from seed>
+
+## Constraints
+
+<constraints as bullet list>
+
+## Acceptance Criteria
+
+- [ ] <criterion_1>
+- [ ] <criterion_2>
+- ...
+
+## Ontology
+
+| Field | Type | Description |
+|-------|------|-------------|
+| <field_name> | <type> | <description> |
+
+## Evaluation Principles
+
+| Principle | Weight | Description |
+|-----------|--------|-------------|
+| <name> | <weight> | <description> |
+
+## Exit Conditions
+
+<exit conditions as bullet list>
+
+---
+
+**Seed ID**: `<seed_id or pm_id>` | **Ambiguity Score**: <score> | **Seed**: `<seed_file_path>`
+*Generated by [Ouroboros](https://github.com/Q00/ouroboros) via `ooo publish`*
+BODY
+)"
+```
+
+Capture the Epic issue number from the output.
+
+**7c. Create Task issues (one per implementation unit):**
+
+For each task:
+
+```bash
+gh issue create -R <TARGET_REPO> \
+  --title "[Task] <task_title>" \
+  --label "ouroboros,task" \
+  --body "$(cat <<'BODY'
+Parent: #<epic_number>
+
+## Scope
+
+<what this task covers>
+
+## Acceptance Criteria
+
+- [ ] <specific_criterion_1>
+- [ ] <specific_criterion_2>
+
+## Test Checklist
+
+- [ ] <test_1>
+- [ ] <test_2>
+- [ ] <test_3>
+
+## Pass Criteria
+
+<measurable conditions for this task to be considered done>
+
+---
+
+*Part of [Epic] #<epic_number> | Generated by [Ouroboros](https://github.com/Q00/ouroboros) via `ooo publish`*
+BODY
+)"
+```
+
+**7d. Update Epic with task links:**
+
+After all tasks are created, add a comment to the Epic:
+
+```bash
+gh issue comment <epic_number> -R <TARGET_REPO> --body "$(cat <<'BODY'
+## Implementation Tasks
+
+- [ ] #<task_1_number> — <task_1_title>
+- [ ] #<task_2_number> — <task_2_title>
+- [ ] #<task_3_number> — <task_3_title>
+
+Track overall progress by checking off tasks as their issues are closed.
+BODY
+)"
+```
+
+### Step 8: Summary
+
+Present the results:
+
+```
+Published to <TARGET_REPO>:
+
+  #<epic>  [Epic] <goal_summary>
+    ├── #<task_1>  [Task] <task_1_title>
+    ├── #<task_2>  [Task] <task_2_title>
+    └── #<task_3>  [Task] <task_3_title>
+
+View: https://github.com/<TARGET_REPO>/issues/<epic>
+```
+
+Then suggest next steps:
+
+```
+Next steps:
+  - Assign tasks to team members on GitHub
+  - Use GitHub Projects board for tracking
+  - Run `ooo run` for AI-assisted implementation of individual tasks
+```
+
+## Notes
+
+- **No MCP required**: This skill works entirely through `gh` CLI
+- **Non-destructive**: Creates new issues only, never modifies existing ones
+- **Cross-repo support**: All `gh` commands use `-R <TARGET_REPO>`, so seeds can be published to any repository the user has write access to
+- **Works with both seed formats**: YAML seeds from `ooo seed` and JSON seeds from `ooo pm` are both supported — the parser auto-detects format by file extension

{ouroboros_ai-0.26.7.dev2 → ouroboros_ai-0.26.7.dev4}/src/ouroboros/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.26.7.dev2'
-__version_tuple__ = version_tuple = (0, 26, 7, 'dev2')
+__version__ = version = '0.26.7.dev4'
+__version_tuple__ = version_tuple = (0, 26, 7, 'dev4')
 
 __commit_id__ = commit_id = None

{ouroboros_ai-0.26.7.dev2 → ouroboros_ai-0.26.7.dev4}/src/ouroboros/mcp/client/adapter.py

@@ -289,26 +289,21 @@ class MCPClientAdapter:
     async def disconnect(self) -> Result[None, MCPClientError]:
         """Disconnect from the current MCP server.
 
+        Releases both the MCP session and the underlying transport context
+        manager in reverse acquisition order.  Always attempts to close both
+        resources even when one teardown raises.
+
         Returns:
             Result containing None on success or MCPClientError on failure.
         """
         if self._session is None and self._transport_cm is None:
             return Result.ok(None)
 
-        session = self._session
-        transport_cm = self._transport_cm
-        self._session = None
-        self._transport_cm = None
-        self._read_stream = None
-        self._write_stream = None
-        self._server_info = None
+        server_name = self._config.name if self._config else "unknown"
 
         try:
-            if session is not None:
-                await session.__aexit__(None, None, None)
-            if transport_cm is not None:
-                await transport_cm.__aexit__(None, None, None)
-            log.info("mcp.disconnected", server=self._config.name if self._config else "unknown")
+            await self._reset_connection_state()
+            log.info("mcp.disconnected", server=server_name)
             return Result.ok(None)
         except Exception as e:
             return Result.err(

ouroboros_ai-0.26.7.dev4/tests/unit/mcp/client/test_adapter_transport_lifecycle.py

@@ -0,0 +1,225 @@
+"""Tests for STDIO transport context manager lifecycle in MCPClientAdapter.
+
+Covers the edge cases identified in PR #263 review:
+1. Rollback on failed initialization (transport entered but session fails)
+2. disconnect() cleans transport when session is None (partial connect)
+3. disconnect() closes transport even when session.__aexit__ raises
+4. Transport teardown errors are surfaced, not swallowed
+"""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from ouroboros.mcp.client.adapter import MCPClientAdapter
+from ouroboros.mcp.types import MCPServerConfig, TransportType
+
+
+def _make_stdio_config(name: str = "test") -> MCPServerConfig:
+    return MCPServerConfig(
+        name=name,
+        transport=TransportType.STDIO,
+        command="echo",
+        args=("hello",),
+    )
+
+
+def _mock_transport_cm(read=None, write=None):
+    """Create a mock stdio_client context manager."""
+    cm = MagicMock()
+    cm.__aenter__ = AsyncMock(return_value=(read or MagicMock(), write or MagicMock()))
+    cm.__aexit__ = AsyncMock(return_value=None)
+    return cm
+
+
+def _mock_session(*, init_fail=False, exit_fail=False):
+    """Create a mock ClientSession."""
+    session = MagicMock()
+    session.__aenter__ = AsyncMock(return_value=session)
+    if exit_fail:
+        session.__aexit__ = AsyncMock(side_effect=RuntimeError("session exit boom"))
+    else:
+        session.__aexit__ = AsyncMock(return_value=None)
+    if init_fail:
+        session.initialize = AsyncMock(side_effect=ConnectionError("init failed"))
+    else:
+        session.initialize = AsyncMock(
+            return_value=MagicMock(
+                serverInfo=MagicMock(name="test", version="1.0"),
+                protocolVersion="2024-11-05",
+                capabilities=MagicMock(tools=None, resources=None, prompts=None, logging=None),
+            )
+        )
+    return session
+
+
+class TestConnectRollback:
+    """Finding #1: rollback transport on failed session init."""
+
+    @pytest.mark.asyncio
+    async def test_transport_closed_when_session_init_fails(self):
+        """If initialize() fails after transport is entered, transport must be closed."""
+        adapter = MCPClientAdapter(max_retries=1)
+        transport_cm = _mock_transport_cm()
+        session = _mock_session(init_fail=True)
+
+        with (
+            patch("mcp.client.stdio.stdio_client", return_value=transport_cm),
+            patch("mcp.ClientSession", return_value=session),
+        ):
+            result = await adapter.connect(_make_stdio_config())
+
+        assert result.is_err
+        # Transport must have been cleaned up (called once per retry attempt)
+        transport_cm.__aexit__.assert_called_with(None, None, None)
+        assert adapter._transport_cm is None
+        assert adapter._session is None
+
+    @pytest.mark.asyncio
+    async def test_transport_closed_when_session_enter_fails(self):
+        """If session.__aenter__ fails, transport must be closed."""
+        adapter = MCPClientAdapter()
+        transport_cm = _mock_transport_cm()
+        session = MagicMock()
+        session.__aenter__ = AsyncMock(side_effect=RuntimeError("session enter boom"))
+
+        with (
+            patch("mcp.client.stdio.stdio_client", return_value=transport_cm),
+            patch("mcp.ClientSession", return_value=session),
+        ):
+            result = await adapter.connect(_make_stdio_config())
+
+        assert result.is_err
+        transport_cm.__aexit__.assert_called_once()
+        assert adapter._transport_cm is None
+
+
+class TestDisconnectPartialConnect:
+    """Finding #2: disconnect() must clean transport even when session is None."""
+
+    @pytest.mark.asyncio
+    async def test_disconnect_cleans_orphaned_transport(self):
+        """If _session is None but _transport_cm is set, disconnect must close it."""
+        adapter = MCPClientAdapter()
+        adapter._config = _make_stdio_config()
+        adapter._session = None  # No session
+
+        transport_cm = _mock_transport_cm()
+        adapter._transport_cm = transport_cm  # But transport is open
+
+        result = await adapter.disconnect()
+        assert result.is_ok
+        transport_cm.__aexit__.assert_called_once_with(None, None, None)
+        assert adapter._transport_cm is None
+
+    @pytest.mark.asyncio
+    async def test_disconnect_noop_when_both_none(self):
+        """If both session and transport are None, disconnect is a no-op."""
+        adapter = MCPClientAdapter()
+        result = await adapter.disconnect()
+        assert result.is_ok
+
+
+class TestDisconnectSessionFailure:
+    """Finding #3: transport cleanup must run even when session exit raises."""
+
+    @pytest.mark.asyncio
+    async def test_transport_closed_when_session_exit_raises(self):
+        """If session.__aexit__ raises, transport must still be closed."""
+        adapter = MCPClientAdapter()
+        adapter._config = _make_stdio_config()
+
+        session = _mock_session(exit_fail=True)
+        adapter._session = session
+
+        transport_cm = _mock_transport_cm()
+        adapter._transport_cm = transport_cm
+
+        result = await adapter.disconnect()
+        # Should report the error
+        assert result.is_err
+        # But transport must still be cleaned up
+        transport_cm.__aexit__.assert_called_once_with(None, None, None)
+        assert adapter._transport_cm is None
+        assert adapter._session is None
+
+
+class TestDisconnectErrorReporting:
+    """Finding #4: transport teardown errors must be surfaced."""
+
+    @pytest.mark.asyncio
+    async def test_transport_exit_error_is_reported(self):
+        """If transport.__aexit__ raises, the error must be in the Result."""
+        adapter = MCPClientAdapter()
+        adapter._config = _make_stdio_config()
+        adapter._session = None  # Only transport
+
+        transport_cm = MagicMock()
+        transport_cm.__aexit__ = AsyncMock(side_effect=OSError("pipe broken"))
+        adapter._transport_cm = transport_cm
+
+        result = await adapter.disconnect()
+        assert result.is_err
+        assert "pipe broken" in str(result.error)
+        # Transport ref still cleaned up
+        assert adapter._transport_cm is None
+
+    @pytest.mark.asyncio
+    async def test_both_errors_reported_session_first(self):
+        """If both session and transport raise, session error is primary."""
+        adapter = MCPClientAdapter()
+        adapter._config = _make_stdio_config()
+
+        session = _mock_session(exit_fail=True)
+        adapter._session = session
+
+        transport_cm = MagicMock()
+        transport_cm.__aexit__ = AsyncMock(side_effect=OSError("transport boom"))
+        adapter._transport_cm = transport_cm
+
+        result = await adapter.disconnect()
+        assert result.is_err
+        # First error (session) is primary
+        assert "session exit boom" in str(result.error)
+        # Both resources cleaned up
+        assert adapter._session is None
+        assert adapter._transport_cm is None
+
+
+class TestHappyPath:
+    """Verify the fix doesn't break normal connect/disconnect."""
+
+    @pytest.mark.asyncio
+    async def test_normal_connect_stores_transport_cm(self):
+        adapter = MCPClientAdapter()
+        transport_cm = _mock_transport_cm()
+        session = _mock_session()
+
+        with (
+            patch("mcp.client.stdio.stdio_client", return_value=transport_cm),
+            patch("mcp.ClientSession", return_value=session),
+        ):
+            result = await adapter.connect(_make_stdio_config())
+
+        assert result.is_ok
+        assert adapter._transport_cm is transport_cm
+        assert adapter._session is not None
+
+    @pytest.mark.asyncio
+    async def test_normal_disconnect_cleans_both(self):
+        adapter = MCPClientAdapter()
+        adapter._config = _make_stdio_config()
+
+        session = _mock_session()
+        adapter._session = session
+        transport_cm = _mock_transport_cm()
+        adapter._transport_cm = transport_cm
+
+        result = await adapter.disconnect()
+        assert result.is_ok
+        session.__aexit__.assert_called_once()
+        transport_cm.__aexit__.assert_called_once()
+        assert adapter._session is None
+        assert adapter._transport_cm is None