conexus 2.3.1__tar.gz → 2.3.3__tar.gz

{conexus-2.3.1 → conexus-2.3.3}/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
       "name": "nx",
       "source": "./nx",
       "description": "Self-hosted three-tier knowledge management with 15 specialized agents, semantic search, and RDR decision tracking for Claude Code.",
-      "version": "2.3.1"
+      "version": "2.3.3"
     }
   ]
 }

{conexus-2.3.1 → conexus-2.3.3}/CHANGELOG.md

@@ -6,6 +6,33 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [2.3.3] - 2026-03-23
+
+### Fixed
+- **Python 3.14 compatibility** — `import voyageai` at module level in `t3.py`
+  crashed on Python 3.14 due to Pydantic v1 incompatibility in the voyageai SDK.
+  Import is now guarded with `try/except`; cloud mode raises a clear error, local
+  mode works without voyageai.
+
+## [2.3.2] - 2026-03-22
+
+### Fixed
+- **Planning chain bypass prevention** — agents can no longer skip the
+  strategic-planner → plan-auditor → plan-enricher chain by creating beads
+  directly or compensating when subagents fail. PROHIBITION block added to
+  rdr-accept, chain mandatory for multi-phase RDRs.
+- **Silent bead content corruption** — `bd update --description "..."` silently
+  destroys multi-line markdown (backticks, `$variables`, nested quotes). Replaced
+  with Write tool → `--body-file` pattern in plan-enricher agent and skill.
+- **Dead T2 idempotency code** — removed Python comparisons against always-None
+  `t2_status`; self-healing logic moved to Action section with live `memory_get`.
+- **Unbound placeholders** — fixed `{id}`, `{t2_status}`, `{repo_name}`, `{type}`
+  leaking from Python into agent instructions; standardized to `<ID>` notation.
+
+### Added
+- **Known Pitfalls** section in writing-nx-skills skill — documents the
+  `--description` corruption bug so future agent authors use `--body-file`.
+
 ## [2.3.1] - 2026-03-22
 
 ### Fixed

{conexus-2.3.1 → conexus-2.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: conexus
-Version: 2.3.1
+Version: 2.3.3
 Summary: Self-hosted semantic search and knowledge management for LLM-driven development
 Project-URL: Homepage, https://github.com/Hellblazer/nexus
 Project-URL: Repository, https://github.com/Hellblazer/nexus

{conexus-2.3.1 → conexus-2.3.3}/nx/CHANGELOG.md

@@ -6,6 +6,25 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [2.3.3] - 2026-03-23
+
+Plugin version aligned with Nexus CLI 2.3.3. No plugin-level functional changes.
+
+## [2.3.2] - 2026-03-22
+
+### Fixed
+- **rdr-accept**: PROHIBITION block prevents orchestrator from bypassing
+  planning chain. Chain mandatory for multi-phase RDRs. Subagent failure
+  clause blocks "let me finish this directly" compensation. Dead T2
+  idempotency code removed; self-healing uses live memory_get results.
+  Unbound placeholders fixed with `<ID>` notation.
+- **plan-enricher**: `bd update --description` replaced with Write tool →
+  `--body-file` pattern. Prevents silent content corruption from shell escaping.
+- **enrich-plan skill**: Standalone invocation path updated to match agent fix.
+
+### Added
+- **writing-nx-skills**: Known Pitfalls section for `--description` corruption.
+
 ## [2.3.1] - 2026-03-22
 
 ### Fixed

{conexus-2.3.1 → conexus-2.3.3}/nx/agents/plan-enricher.md

@@ -114,10 +114,13 @@ For each child bead, update its description with:
 
 ### Step 4: Update Beads
 
-For each enriched bead:
-```bash
-bd update <id> --description "enriched content"
-```
+For each enriched bead, two actions in sequence:
+
+**Step 4a** — Write enriched content to a temp file using the **Write tool** (file_path: `/tmp/bead-<id>.md`, content: the enriched markdown). Do NOT use echo, cat, or heredoc — use the Write tool.
+
+**Step 4b** — Update the bead from the file: `bd update <id> --body-file /tmp/bead-<id>.md`
+
+**IMPORTANT**: Do NOT use `--description "..."` for multi-line or markdown content — shell escaping silently corrupts backticks, `$variables`, and nested quotes without raising an error. Always use `--body-file`.
 
 ## T2 Persistence
 
@@ -154,7 +157,7 @@ This agent follows the [Shared Context Protocol](./_shared/CONTEXT_PROTOCOL.md).
 See [ERROR_HANDLING.md](./_shared/ERROR_HANDLING.md) for common error patterns and recovery.
 
 ### Agent-Specific PRODUCE
-- **Enriched Beads**: Updated via `bd update <id> --description "..."` with execution-ready context
+- **Enriched Beads**: Updated via Write tool → `bd update <id> --body-file /tmp/bead-<id>.md` with execution-ready context
 - **T2 memory**: Epic bead ID written via memory_put tool: project="{repo}_rdr", title="NNN"
 - **T1 scratch**: Enrichment summary via scratch tool: action="put", tags="enrichment-complete"
 - **Console output**: Enriched plan summary table
@@ -168,7 +171,7 @@ Store using these naming conventions:
 **CRITICAL**: Complete all data persistence BEFORE generating final response.
 
 **Sequence** (follow strictly):
-1. **Update All Beads**: Run `bd update` for every enriched bead
+1. **Update All Beads**: For each bead — Write content to `/tmp/bead-<id>.md` via Write tool, then `bd update <id> --body-file /tmp/bead-<id>.md` (never `--description`)
 2. **Write T2 Record**: Store epic bead ID and enrichment metadata via memory_put tool
 3. **Write T1 Summary**: Store enrichment summary to scratch
 4. **Verify Persistence**: Confirm beads updated (bd show <id> for sample), T2 written (memory_get)

conexus-2.3.3/nx/commands/rdr-accept.md

@@ -0,0 +1,262 @@
+---
+description: Accept a gated RDR — verifies gate PASSED in T2, updates status to accepted
+---
+
+# RDR Accept
+
+!{
+NEXUS_RDR_ARGS="${ARGUMENTS:-}" python3 << 'PYEOF'
+import os, sys, re, subprocess
+from pathlib import Path
+
+args = os.environ.get('NEXUS_RDR_ARGS', '').strip()
+
+# Repo root and name
+try:
+    repo_root = subprocess.check_output(
+        ['git', 'rev-parse', '--show-toplevel'],
+        stderr=subprocess.DEVNULL, text=True).strip()
+    repo_name = os.path.basename(repo_root)
+except Exception:
+    repo_root = os.getcwd()
+    repo_name = os.path.basename(repo_root)
+
+# Resolve RDR directory from .nexus.yml (default: docs/rdr)
+rdr_dir = 'docs/rdr'
+nexus_yml = Path(repo_root) / '.nexus.yml'
+if nexus_yml.exists():
+    content = nexus_yml.read_text()
+    try:
+        import yaml
+        d = yaml.safe_load(content) or {}
+        paths = (d.get('indexing') or {}).get('rdr_paths', ['docs/rdr'])
+        rdr_dir = paths[0] if paths else 'docs/rdr'
+    except ImportError:
+        m_yml = (re.search(r'rdr_paths[^\[]*\[([^\]]+)\]', content) or
+                 re.search(r'rdr_paths:\s*\n\s+-\s*(.+)', content))
+        if m_yml:
+            v = m_yml.group(1)
+            parts = re.findall(r'[a-z][a-z0-9/_-]+', v)
+            rdr_dir = parts[0] if parts else 'docs/rdr'
+
+rdr_path = Path(repo_root) / rdr_dir
+
+print(f"**Repo:** `{repo_name}`  **RDR directory:** `{rdr_dir}`")
+print()
+
+
+def parse_frontmatter(filepath):
+    text = filepath.read_text(errors='replace')
+    meta = {}
+    if text.startswith('---'):
+        parts = text.split('---', 2)
+        if len(parts) >= 3:
+            block = parts[1]
+            try:
+                import yaml; meta = yaml.safe_load(block) or {}
+            except Exception:
+                for line in block.splitlines():
+                    if ':' in line:
+                        k, _, v = line.partition(':')
+                        meta[k.strip().lower()] = v.strip()
+    if 'title' not in meta and 'name' not in meta:
+        h1 = re.search(r'^#\s+(.+)', text, re.MULTILINE)
+        if h1:
+            meta['title'] = h1.group(1).strip()
+    return meta, text
+
+
+def find_rdr_file(rdr_path, id_str):
+    m = re.search(r'\d+', id_str)
+    if not m:
+        return None
+    num_int = int(m.group(0))
+    for f in sorted(rdr_path.glob('*.md')):
+        nums = re.findall(r'\d+', f.stem)
+        if nums and int(nums[0]) == num_int:
+            return f
+    return None
+
+
+EXCLUDED = {'readme.md', 'template.md', 'index.md', 'overview.md', 'workflow.md', 'templates.md'}
+
+def get_all_rdrs(rdr_path):
+    """Return list of dicts for all RDRs in the directory."""
+    all_md = sorted(rdr_path.glob('*.md'))
+    rdrs = []
+    for f in all_md:
+        if f.name.lower() in EXCLUDED:
+            continue
+        fm, text = parse_frontmatter(f)
+        rtype = fm.get('type', '?')
+        doc_status = fm.get('status', '?')
+        if doc_status == '?' and rtype == '?':
+            continue
+        rdrs.append({
+            'file': f.name,
+            'path': f,
+            'title': fm.get('title', fm.get('name', f.stem)),
+            'status': doc_status,
+            'rtype': rtype,
+            'priority': fm.get('priority', '?'),
+        })
+    return rdrs
+
+
+if not rdr_path.exists():
+    print(f"> No RDRs found — `{rdr_dir}` does not exist in this repo.")
+    sys.exit(0)
+
+id_match = re.search(r'\d+', args)
+
+if not id_match:
+    print("> **Usage**: `/nx:rdr-accept <id>` — e.g. `/nx:rdr-accept 003` or `/nx:rdr-accept RDR-003`")
+    print()
+    rdrs = get_all_rdrs(rdr_path)
+    draft_rdrs = [r for r in rdrs if r['status'].lower() == 'draft']
+    print("### Draft RDRs (eligible for acceptance)")
+    print()
+    if draft_rdrs:
+        print("| File | Title | Status | Type |")
+        print("|------|-------|--------|------|")
+        for r in draft_rdrs:
+            print(f"| {r['file']} | {r['title']} | {r['status']} | {r['rtype']} |")
+    else:
+        print("No Draft RDRs found. Only Draft RDRs can be accepted.")
+    sys.exit(0)
+
+rdr_file = find_rdr_file(rdr_path, id_match.group(0))
+if not rdr_file:
+    print(f"> RDR not found for ID: `{id_match.group(0)}`")
+    sys.exit(0)
+
+fm, text = parse_frontmatter(rdr_file)
+title = fm.get('title', fm.get('name', rdr_file.stem))
+current_status = fm.get('status', '?')
+rdr_type = fm.get('type', '?')
+rdr_num = re.search(r'\d+', rdr_file.stem)
+t2_key = rdr_num.group(0) if rdr_num else rdr_file.stem
+
+print(f"### RDR: {rdr_file.name}")
+print(f"**RDR ID:** {t2_key}  **Title:** {title}  **Type:** {rdr_type}  **File Status:** {current_status}")
+print()
+
+# Accepted status is allowed — agent handles idempotency in Step 1
+if current_status.lower() not in ('draft', 'accepted'):
+    print(f"> **BLOCKED**: RDR status is `{current_status}`. Only Draft RDRs can be accepted.")
+    sys.exit(0)
+
+# T2 lookups — agent must call these MCP tools and use the results in the Action section
+print("### T2 Lookups (call these before executing Action steps)")
+print()
+print(f"1. **T2 metadata**: Use **memory_get** tool: project=\"{repo_name}_rdr\", title=\"{t2_key}\"")
+print(f"2. **T2 gate result**: Use **memory_get** tool: project=\"{repo_name}_rdr\", title=\"{t2_key}-gate-latest\"")
+print(f"   If no gate record exists, run `/nx:rdr-gate {t2_key}` first.")
+print()
+print(f"**RDR file path:** `{rdr_file}`")
+print()
+
+# Phase count auto-detection for planning handoff
+ip_match = re.search(
+    r'^## Implementation Plan\s*\n(.*?)(?=^## |\Z)',
+    text, re.MULTILINE | re.DOTALL)
+phase_count = 0
+has_impl_plan = ip_match is not None
+if has_impl_plan:
+    phase_count = len(re.findall(r'^### Phase', ip_match.group(1), re.MULTILINE))
+
+print("### Planning Handoff")
+print(f"**Phase count detected:** {phase_count}")
+print(f"**Has Implementation Plan section:** {'yes' if has_impl_plan else 'no'}")
+if phase_count >= 2:
+    print("**Recommendation:** Invoke strategic planner (multi-phase RDR)")
+    print("**Default:** yes")
+elif not has_impl_plan:
+    print("**Warning:** No Implementation Plan section detected — this RDR may not be ready for planning.")
+    print("**Recommendation:** Skip planning")
+    print("**Default:** no")
+else:
+    print("**Recommendation:** Skip planning (single-phase)")
+    print("**Default:** no")
+print()
+PYEOF
+}
+
+## RDR to Accept
+
+$ARGUMENTS
+
+## Action
+
+> **PROHIBITION — PLANNING CHAIN INTEGRITY**
+> You MUST NOT create beads, write plans, enrich beads, or perform any planning/enrichment work yourself.
+> You are the **orchestrator only**. Running `bd create`, `bd dep add`, `bd update --description`,
+> or writing plan content in the Planning Chain is a HARD STOP — halt and report the error.
+> Only the dispatched subagents (strategic-planner, plan-auditor, plan-enricher) do this work.
+> Doing it yourself bypasses the audit and enrichment chain, producing unvalidated plans.
+>
+> **SUBAGENT FAILURE**: If any subagent in the chain fails or returns partial results,
+> you MUST NOT compensate by doing the subagent's work yourself. Report the failure,
+> state which step broke, and provide the retry command. "Let me finish this directly"
+> is the exact behavior this prohibition exists to prevent.
+>
+> If the Agent tool is not available (e.g., you are a subagent), report:
+> "Cannot dispatch planning chain — Agent tool unavailable. Run /nx:rdr-accept from the main conversation."
+
+All RDR metadata is pre-loaded above. Step 8 requires additional tool calls for planning dispatch.
+
+**Notation**: All references to `<ID>` below mean the **RDR ID** value from the script output (e.g. `027`). All references to `<type>` mean the **Type** value (e.g. `design`). Substitute with the actual values.
+
+**Before executing steps below**, call both T2 lookups listed above (memory_get for metadata and gate result). You need these results for Steps 1–2.
+
+- **Step 1 — T2 idempotency and self-healing**: Compare the **File Status** (from script output above) against the **T2 metadata status** (from your memory_get call):
+  - **Both show `accepted`**: True no-op. Print `> RDR is already accepted (file and T2 agree). Nothing to do.` and stop.
+  - **File shows `accepted`, T2 does not**: Self-healing — update T2 to match file. Print `> Self-healing: file shows accepted but T2 shows <actual-T2-status>. Updating T2.` Use memory_put to set T2 status to `accepted`. Then stop (no further steps needed).
+  - **T2 shows `accepted`, file shows `draft`**: Self-healing — update file to match T2. Print `> Self-healing: T2 shows accepted but file shows draft. Updating file.` Change file frontmatter to `status: accepted` and `git add` the updated file. Then stop.
+  - **File shows `draft` and T2 shows `draft` (or T2 record not found)**: Normal flow — proceed to Step 2.
+- **Step 2 — Verify gate**: Check that the T2 gate result (from your memory_get call) shows `outcome: "PASSED"`. If the record exists but `outcome` is absent or is not `"PASSED"`, treat as BLOCKED. If no gate record exists at all, also BLOCKED. Report **BLOCKED** and stop. Print: `> Run /nx:rdr-gate <ID> first.`
+- **Step 3 — Update T2** (T2 is the process authority):
+  Use **memory_put** tool: content="status: accepted\naccepted_date: <today YYYY-MM-DD>\ntitle: <title>\ntype: <type>\n(preserve other fields from T2 Metadata lookup)", project="<repo-name>_rdr" (same project as in the T2 Lookups above), title="<ID>", ttl="permanent", tags="rdr,<type>"
+- **Step 4 — Update the RDR file**: Change `status: draft` to `status: accepted` in the YAML frontmatter. Add `accepted_date: YYYY-MM-DD` if not present.
+- **Step 5 — Update `reviewed-by`**: If `reviewed-by` is empty or placeholder, set to `self` (solo review).
+- **Step 6 — Regenerate README**: Update `<rdr-dir>/README.md` (the RDR directory from the script output header) index to reflect the new status.
+- **Step 7 — Stage files**: `git add` the modified RDR file and README.
+- **Step 8 — Planning handoff**: Use the phase count and recommendation from the script output above.
+  - **If phase_count >= 2**: The planning chain is **MANDATORY**. Do not ask — print `> Multi-phase RDR — dispatching planning chain (mandatory).` and proceed to the Planning Chain below.
+  - **If phase_count < 2**: Ask: "Invoke strategic planner to build execution beads? (y/n) [default: no]"
+    - **If no:** Accept is complete. Print: `> RDR <ID> accepted. Ready for implementation.`
+    - **If yes:** Proceed to the Planning Chain below.
+
+---
+
+### Planning Chain (triggered from Step 8 above)
+
+Execute these steps sequentially when the planning handoff triggers (mandatory multi-phase or user opted in). **Reminder: you are the orchestrator. Do NOT create beads or plans yourself.**
+
+**Step 8a — Write T1 context:**
+Write T1 scratch entry: Use scratch tool: action="put", content="RDR-<ID>: planning context for <title>. RDR file: <RDR-file-path>", tags="rdr-planning-context,rdr-<ID>"
+
+**Step 8b — Dispatch strategic-planner (MANDATORY — do NOT do this yourself):**
+Dispatch `nx:strategic-planner` agent (via Agent tool, subagent_type="nx:strategic-planner") with prompt:
+> Create phased execution plan for RDR-<ID>: <title>. RDR file: <RDR-file-path>. Read the RDR content for implementation phases. Create epic and task beads with dependencies.
+
+**Wait for the planner to complete before proceeding.**
+Note the plan file path and bead IDs from the planner's output.
+**If the planner did not create beads, this is a failure — report it and stop. The RDR acceptance is still valid. To retry the planning chain only, run `/nx:create-plan` manually with the RDR file path.**
+
+**Step 8c — Dispatch plan-auditor (MANDATORY — do NOT skip):**
+After the planner completes, dispatch `nx:plan-auditor` agent (via Agent tool, subagent_type="nx:plan-auditor") with prompt:
+> Audit the execution plan just created for RDR-<ID>: <title>. Check T1 scratch for rdr-planning-context. Validate the plan against the codebase. Check beads created by the planner.
+
+**Wait for the auditor to complete before proceeding. Do NOT skip this step.**
+
+**Step 8d — Dispatch plan-enricher (MANDATORY — do NOT skip):**
+After the auditor completes, dispatch `nx:plan-enricher` agent (via Agent tool, subagent_type="nx:plan-enricher") with prompt:
+> Enrich all beads for RDR-<ID>: <title> with audit findings from T1 scratch. Write epic bead ID to T2.
+
+**Wait for the enricher to complete. Do NOT skip this step.**
+
+**Step 8e — Verify chain completion:**
+Confirm all three agents ran: planner created beads, auditor validated, enricher enriched.
+Print: `> RDR-<ID> accepted. Planning chain complete: planner → auditor → enricher. Use 'bd ready' to see executable tasks.`
+**If any step was skipped or failed, report which step broke the chain and provide the retry command.**

{conexus-2.3.1 → conexus-2.3.3}/nx/skills/enrich-plan/SKILL.md

@@ -46,7 +46,7 @@ T1 scratch is session-scoped. Standalone invocation only works within the same s
 
 ## Agent-Specific PRODUCE
 
-- **Enriched Beads**: Updated via `bd update <id> --description "..."` with execution-ready context
+- **Enriched Beads**: Updated via Write tool → `bd update <id> --body-file /tmp/bead-<id>.md` with execution-ready context
 - **T2 memory**: Epic bead ID written via memory_put tool: project="{repo}_rdr", title="NNN"
 - **T1 scratch**: Enrichment summary via scratch tool: action="put", tags="enrichment-complete"
 - **Console output**: Enriched plan summary table

{conexus-2.3.1 → conexus-2.3.3}/nx/skills/writing-nx-skills/SKILL.md

@@ -89,6 +89,23 @@ After creating a skill, update `nx/registry.yaml`:
 
 When adding a new skill, also add it to `nx/skills/using-nx-skills/SKILL.md` routing tree. This file is injected every session — if your skill isn't listed there, it won't be discovered.
 
+## Known Pitfalls
+
+### bd update --description silently corrupts multi-line content
+
+**Never** instruct agents to use `bd update <id> --description "..."` for multi-line or markdown content. Shell escaping silently destroys backticks (executed as command substitution), `$variables` (expanded to empty), and nested quotes (break argument boundaries). No error is raised — the command reports success with mangled data.
+
+**Correct pattern**: Write content to a temp file via the Write tool, then use `--body-file`:
+
+```
+Step 1 — Write enriched content using the Write tool (file_path: /tmp/bead-<id>.md)
+Step 2 — bd update <id> --body-file /tmp/bead-<id>.md
+```
+
+Short single-phrase values (e.g. `--design "revised scope"`) are safe. The bug only affects multi-line content with markdown formatting.
+
+This applies to `--description`, `--notes`, `--design`, and any flag that accepts free-text content longer than a simple phrase. Use `--body-file` or `--design-file` respectively.
+
 ## Quality Checklist
 
 - [ ] Frontmatter has `name`, `description`, and `effort`

{conexus-2.3.1 → conexus-2.3.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "conexus"
-version = "2.3.1"
+version = "2.3.3"
 description = "Self-hosted semantic search and knowledge management for LLM-driven development"
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.12"

{conexus-2.3.1 → conexus-2.3.3}/src/nexus/db/t3.py

@@ -11,10 +11,14 @@ from typing import Literal
 import chromadb
 import chromadb.errors
 import httpx
-import voyageai
 from chromadb.errors import NotFoundError as _ChromaNotFoundError
 import structlog
 
+try:
+    import voyageai
+except Exception:  # Pydantic v1 crashes on Python ≥ 3.14
+    voyageai = None  # type: ignore[assignment]
+
 from nexus.config import get_credential
 from nexus.corpus import embedding_model_for_collection, index_model_for_collection
 from nexus.db.chroma_quotas import QUOTAS, QuotaValidator
@@ -92,6 +96,12 @@ class T3Database:
             return
 
         # ── Cloud mode ───────────────────────────────────────────────────
+        if voyageai is None:
+            raise ImportError(
+                "voyageai is required for cloud mode but failed to import "
+                "(likely Pydantic v1 incompatibility with Python ≥ 3.14). "
+                "Use local mode (NX_LOCAL_MODE=1) or downgrade to Python ≤ 3.13."
+            )
         self._voyage_client: voyageai.Client | None = (
             voyageai.Client(api_key=voyage_api_key, timeout=read_timeout_seconds, max_retries=3)
             if voyage_api_key else None

{conexus-2.3.1 → conexus-2.3.3}/tests/hooks/test_stop_failure_hook.py

@@ -40,6 +40,7 @@ def _run_hook(
     env = {
         **os.environ,
         "PATH": os.environ.get("PATH", ""),
+        "CLAUDECODE": "",  # Prevent side effects (bd remember/create) in tests
         **(env_overrides or {}),
     }
     return subprocess.run(

{conexus-2.3.1 → conexus-2.3.3}/uv.lock

@@ -489,7 +489,7 @@ wheels = [
 
 [[package]]
 name = "conexus"
-version = "2.3.1"
+version = "2.3.3"
 source = { editable = "." }
 dependencies = [
     { name = "chromadb" },