release: v0.3.0

.github/workflows/ci.yml

@@ -179,6 +179,17 @@ jobs:
       - name: npm launcher unit tests
         run: node --test
         working-directory: npm/mycelium
+      # RFC-0111: SDK thin-wrapper. Unit tests are hermetic (injected spawn);
+      # the integration test then round-trips real JSON through the SDK using
+      # the release binary just built above, proving the --format json contract.
+      - name: SDK unit tests
+        run: node --test
+        working-directory: npm/sdk
+      - name: SDK integration test (against built binary)
+        run: node --test
+        working-directory: npm/sdk
+        env:
+          MYCELIUM_BIN: ${{ github.workspace }}/target/release/mycelium
       - name: npm packaging smoke test (assemble → install → run)
         run: |
           set -euo pipefail
@@ -190,6 +201,37 @@ jobs:
           OUT="$(node_modules/.bin/mycelium --version)"
           echo "launcher output: $OUT"
           echo "$OUT" | grep -qi mycelium
+      # RFC-0111: prove the assembled SDK resolves the prebuilt binary from its
+      # pinned optionalDependency (no MYCELIUM_BIN, no PATH) — the exact
+      # no-Cargo install path a fresh `npm i @aimasteracc/mycelium-sdk` takes.
+      - name: SDK packaging smoke test (assemble → install → resolve binary → query)
+        run: |
+          set -euo pipefail
+          mkdir -p sdk-smoke && cd sdk-smoke && npm init -y >/dev/null
+          npm install --install-links \
+            ../dist-npm/mycelium-linux-x64-gnu ../dist-npm/mycelium-sdk >/dev/null
+          node -e '
+            const { Mycelium } = require("@aimasteracc/mycelium-sdk");
+            const m = new Mycelium({ root: "." });
+            m.version().then((v) => {
+              console.log("sdk resolved binary →", v);
+              if (!/^mycelium /.test(v)) process.exit(1);
+            }).catch((e) => { console.error(e); process.exit(1); });
+          '
+      # RFC-0111 Phase 2: Python SDK (mycelium-rcig). Unit tests are hermetic
+      # (injected spawn, stdlib unittest — no pip install); the integration run
+      # round-trips real JSON through the SDK using the release binary above.
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+      - name: Python SDK unit tests
+        run: python -m unittest discover -s tests
+        working-directory: bindings/python
+      - name: Python SDK integration test (against built binary)
+        run: python -m unittest discover -s tests
+        working-directory: bindings/python
+        env:
+          MYCELIUM_BIN: ${{ github.workspace }}/target/release/mycelium
 
   doc-build:
     name: docs (rustdoc + mdbook)
@@ -226,7 +268,13 @@ jobs:
 
   dco-check:
     name: DCO sign-off
-    if: github.event_name == 'pull_request'
+    # Skip for release/* and hotfix/* → main PRs. Those branches are managed
+    # by release.yml which intentionally skips DCO (squash-merge artifacts from
+    # develop don't carry Signed-off-by trailers; the source PRs were checked).
+    if: >
+      github.event_name == 'pull_request' &&
+      !startsWith(github.head_ref, 'release/') &&
+      !startsWith(github.head_ref, 'hotfix/')
     runs-on: ubuntu-latest
     timeout-minutes: 5
     steps:
@@ -239,8 +287,13 @@ jobs:
           # --no-merges so historical PR merge commits (which never carried
           # sign-off and predate DCO enforcement) don't fail back-merge PRs
           # like release/* → develop. Authored commits must still sign off.
+          #
+          # Use full body grep instead of %(trailers:key=...) because GitHub
+          # squash-merge embeds Signed-off-by lines in the middle of the body
+          # (between individual commit entries) rather than as trailing lines,
+          # so the trailer parser misses them and false-fails those commits.
           for sha in $(git rev-list --no-merges ${{ github.event.pull_request.base.sha }}..${{ github.event.pull_request.head.sha }}); do
-            if ! git log -1 --format='%(trailers:key=Signed-off-by,valueonly)' $sha | grep -q .; then
+            if ! git log -1 --format='%B' "$sha" | grep -qiE '^Signed-off-by: .+ <.+>'; then
               echo "::error::Commit $sha lacks Signed-off-by trailer (DCO)."
               MISSING=$((MISSING+1))
             fi

.github/workflows/nightly.yml

@@ -102,14 +102,14 @@ jobs:
         run: cargo install cargo-mutants --locked
       - name: Run mutation tests
         run: |
-          cargo mutants --workspace --timeout 60 --jobs 4 2>&1 | tee mutants.out
+          cargo mutants --workspace --timeout 60 --jobs 4 2>&1 | tee mutants.log
       - name: Enforce >= 70% kill rate
         shell: bash
         run: |
           # cargo-mutants summary line looks like:
           #   "42 missed, 120 caught, 3 unviable, 5 timeout in 5.00s"
           # We extract caught and missed from that line.
-          SUMMARY=$(grep -E 'missed|caught' mutants.out | tail -1)
+          SUMMARY=$(grep -E 'missed|caught' mutants.log | tail -1)
           echo "Summary line: $SUMMARY"
           CAUGHT=$(echo "$SUMMARY" | grep -oP '\d+(?= caught)')
           MISSED=$(echo "$SUMMARY" | grep -oP '\d+(?= missed)')
@@ -134,5 +134,5 @@ jobs:
         if: always()
         with:
           name: mutants-report
-          path: mutants.out
+          path: mutants.log
           if-no-files-found: ignore

.github/workflows/release.yml

@@ -88,7 +88,7 @@ jobs:
     # Gate the first irreversible publish on the CLI binaries building
     # successfully (RFC-0110 / Codex #519 P1): if any platform build fails we
     # must NOT publish to a registry, or the release is partial (crates live but
-    # binaries missing). npm/pypi are gated on publish-crates.
+    # binaries missing). npm/pypi need publish-crates, so they are gated too.
     needs: [validate, quality-recheck, build-cli-binaries]
     runs-on: ubuntu-latest
     timeout-minutes: 60
@@ -220,47 +220,71 @@ jobs:
               return 0
             fi
             if ! ( cd "$dir" && npm publish --access public --provenance ) 2>/tmp/npm_pub_err.log; then
-              npm_err=$(cat /tmp/npm_pub_err.log)
-              # Graceful degradation: scope not yet registered on npmjs.com
-              # (E404 "Scope not found"). Token is present and valid; the @aimasteracc
-              # scope simply needs to be created once via the npmjs.com UI.
-              # Allow ceremony to proceed; npm distribution re-enabled next release.
-              if echo "$npm_err" | grep -qE "E404|Scope not found"; then
-                echo "::warning::npm publish skipped for $name — @aimasteracc scope not yet registered on npmjs.com. See Issue #525."
-                return 0
-              fi
-              echo "$npm_err" >&2
+              # Issue #534: the @aimasteracc scope is registered and NPM_TOKEN
+              # authenticates (npm whoami -> aimasteracc), so ANY publish failure
+              # is a real error — fail the release loudly. The prior E404
+              # graceful-skip (PR #533) masked a non-authenticating token and
+              # produced false-green releases (the v0.2.0 saga). Never again.
+              cat /tmp/npm_pub_err.log >&2
               return 1
             fi
           }
-          # Platform packages must exist before the main package (whose
-          # optionalDependencies reference them).
+          # Platform packages must exist before the main package and the SDK
+          # (whose optionalDependencies reference them). The SDK is published
+          # explicitly after the main package, so skip it in the platform glob.
           for dir in dist-npm/mycelium-*; do
-            [ -d "$dir" ] && publish_one "$dir"
+            [ -d "$dir" ] || continue
+            [ "$dir" = "dist-npm/mycelium-sdk" ] && continue
+            publish_one "$dir"
           done
           publish_one "dist-npm/mycelium"
+          # RFC-0111: thin-CLI-wrapper SDK, published from the same release.
+          publish_one "dist-npm/mycelium-sdk"
 
   publish-pypi:
     name: publish to PyPI
-    needs: [validate, quality-recheck, publish-crates]
+    # GITFLOW registry order is crates.io → npm → PyPI: depend on publish-npm so
+    # a failed/incomplete npm release blocks PyPI (no partial registry release).
+    needs: [validate, quality-recheck, publish-crates, publish-npm]
     runs-on: ubuntu-latest
     timeout-minutes: 30
     environment: pypi
-    permissions:
-      id-token: write  # for Trusted Publishers
+    env:
+      VERSION: ${{ needs.validate.outputs.version }}
     steps:
       - uses: actions/checkout@v6
       - uses: actions/setup-python@v6
         with:
           python-version: '3.12'
-      - run: |
-          if [ -d "bindings/python" ]; then
-            pip install maturin
-            cd bindings/python
-            maturin publish
-          else
+      # RFC-0111 Phase 2: the Python SDK (mycelium-rcig) is a pure-Python thin
+      # CLI wrapper — built with the standard `build` backend, not maturin
+      # (there is no Rust extension). The version is pinned to the release
+      # version.
+      - name: Build the pure-Python SDK wheel
+        id: build
+        run: |
+          set -euo pipefail
+          if [ ! -d "bindings/python" ]; then
             echo "no bindings/python yet — skipping"
+            echo "built=false" >> "$GITHUB_OUTPUT"
+            exit 0
           fi
+          cd bindings/python
+          sed -i -E "s/^version = \".*\"/version = \"$VERSION\"/" pyproject.toml
+          sed -i -E "s/^__version__ = \".*\"/__version__ = \"$VERSION\"/" mycelium_rcig/__init__.py
+          python -m pip install --upgrade build twine
+          python -m build
+      # Token auth (TSA-style: TWINE_USERNAME=__token__ + PYPI_API_TOKEN), not
+      # Trusted Publishers — an account/project-scoped API token publishes a
+      # brand-new package with no pre-configured "pending publisher". Idempotent
+      # via --skip-existing so re-runs never fail on an already-published version.
+      - name: Publish to PyPI (token auth, idempotent)
+        if: steps.build.outputs.built != 'false'
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+          TWINE_NON_INTERACTIVE: "true"
+        run: twine upload --skip-existing bindings/python/dist/*
 
   build-cli-binaries:
     # RFC-0110: cross-compile the `mycelium` CLI for each distributed platform,

.hive/memory/anti-patterns.jsonl

@@ -36,3 +36,4 @@
 {"ts":"2026-06-03T08:00:00Z","agent":"code-reviewer","domain":"async","pattern":"Calling tokio::sync::RwLock::blocking_read() or blocking_write() from inside an async Tokio task","why-bad":"blocking_read() parks the OS thread, which starves the Tokio executor: under any write-lock contention the entire runtime can deadlock; even without contention it reduces throughput. The on_batch FnMut closure inside WatchEngine::drive() is called from an async task — this is the exact failure mode.","instead":"Use try_read() for snapshot-and-continue semantics (skip the batch if briefly contended), or restructure to async read().await before entering the sync callback."}
 {"ts":"2026-06-03T09:11:30Z","agent":"orchestrator","domain":"release-governance","pattern":"release.yml auto-closes the release→main PR on every release without merging (v0.1.6–v0.1.18 all affected)","why-bad":"Creates orphan crates.io/npm/PyPI published versions with no corresponding git tag or main branch commit. Ceremony is left in a broken state requiring manual founder repair every single release. RELEASE_BOT_TOKEN was configured 2026-06-01 but merge step still fails silently and closes the PR.","instead":"Either (1) switch release.yml merge step from gh API to `git push origin release/vX.Y.Z:main` (direct branch push — requires branch protection bypass token), or (2) remove the auto-merge step entirely and let the ceremony script do the merge + tag + release, or (3) use gh pr merge --admin in the workflow with a token that has admin rights. Until fixed, the ceremony script is the only reliable repair path."}
 {"ts":"2026-06-03T19:56:48Z","domain":"git-workflow","pattern":"Committing directly onto local develop after a post-merge 'git checkout develop && pull' sync, because the next increment's branch was never created","why-bad":"Violates the Charter hard rule 'never commit to develop; all work via PR'. The sync step (checkout develop) silently leaves HEAD on develop, so the first commit of the next increment lands on develop. Caught here before push (origin/develop untouched), but a push would have bypassed PR + CI + Codex.","instead":"After merging a PR and syncing develop, IMMEDIATELY 'git checkout -b feature/<next>' before any edit. Or check 'git branch --show-current' is not develop/main before the first commit of an increment."}
+{"ts":"2026-06-04T15:00:00Z","domain":"memory-discipline","pattern":"MCP GitHub tool read prepends resource-reference prefix to file content","why-bad":"When reading files via mcp__github__get_file_contents, the tool prepends '[Resource from github at repo://...]' to the content. If the agent then writes this back to a file (e.g., decisions.jsonl), it rewrites existing lines, violating the append-only Charter constraint. Codex caught this as a P2 on PR #541.","instead":"When using mcp__github__get_file_contents to read memory files, strip the resource-reference prefix before any write-back. Better: use Read (local filesystem tool) for memory files that must stay append-only — never read-then-write memory via the MCP GitHub tool.","ref":"PR#541,Charter§5.3,CLAUDE.md Hard Rules"}