PR1: Core plumbing (CLI modularization, fail-closed CI, bandit)

.github/workflows/ci.yml

@@ -160,32 +160,8 @@ jobs:
           cache-from: type=gha
           cache-to: type=gha,mode=max
 
-  publish:
-    needs: [test, lint, build]
-    runs-on: ubuntu-latest
-    if: github.event_name == 'release'
-
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Download build artifacts
-        uses: actions/download-artifact@v4
-        with:
-          name: dist
-          path: dist/
-
-      - uses: actions/setup-python@v5
-        with:
-          python-version: "3.11"
-
-      - name: Install twine
-        run: pip install twine
-
-      - name: Publish to PyPI
-        env:
-          TWINE_USERNAME: __token__
-          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
-        run: twine upload dist/*
+  # PyPI publish lives solely in publish-pypi.yml (trusted publishing).
+  # Dual upload from this workflow raced on release and is intentionally omitted.
 
   security:
     runs-on: ubuntu-latest
@@ -200,11 +176,23 @@ jobs:
       - name: Install bandit
         run: pip install bandit
 
-      - name: Run bandit security linter
-        run: bandit -r cli/ -f json -o bandit-report.json || true
+      # Fail-closed security policy:
+      # 1) Any HIGH severity finding fails the job (none expected today).
+      # 2) Any finding not in the committed .bandit-baseline.json also fails
+      #    (catches new LOW/MEDIUM drift). Update the baseline deliberately when
+      #    accepting a finding — do not silence with continue-on-error.
+      - name: Run bandit (fail on HIGH)
+        run: bandit -r cli/ -lll -f screen
+
+      - name: Run bandit (fail on new vs baseline)
+        run: bandit -r cli/ -b .bandit-baseline.json -f json -o bandit-report.json
 
       - name: Upload security report
+        if: always()
         uses: actions/upload-artifact@v4
         with:
           name: security-report
           path: bandit-report.json
+          if-no-files-found: warn
+
+

.github/workflows/pack-publish.yml

@@ -14,18 +14,25 @@ jobs:
       - run: |
           python -m pip install --upgrade pip
           python -m pip install -e ".[dev,examples]"
-          u pack --publish
+          u pack publish
       - name: Prepare site
         run: |
-          mkdir -p site
+          mkdir -p site/docs
           echo "<h1>Understanding Pack</h1><ul>" > site/index.html
           for f in docs/glossary.md docs/understanding-dashboard.md; do
-            test -f "$f" && echo "<li><a href='/$f'>$f</a></li>" >> site/index.html
+            if test -f "$f"; then
+              cp "$f" "site/$f"
+              echo "<li><a href='/$f'>$f</a></li>" >> site/index.html
+            fi
           done
-          test -f maps/delta.svg && cp maps/delta.svg site/delta.svg && echo "<li><a href='/site/delta.svg'>delta.svg</a></li>" >> site/index.html || true
+          # Optional nicety: delta.svg may be absent on pack-only publishes.
+          if test -f maps/delta.svg; then
+            cp maps/delta.svg site/delta.svg
+            echo "<li><a href='/delta.svg'>delta.svg</a></li>" >> site/index.html
+          fi
           echo "</ul>" >> site/index.html
       - uses: actions/upload-pages-artifact@v3
-        with: { path: "." }
+        with: { path: "site" }
   deploy:
     needs: build
     permissions:

.github/workflows/pr-delta-comment.yml

@@ -1,39 +1,22 @@
-name: PR Delta Comment
+# DISABLED (Wave 2 consolidation): Soft-failed every step (`|| true`) and duplicated
+# the thin PR map-diff path. Prefer:
+#   .github/workflows/understand-first-pr-analysis.yml
+name: PR Delta Comment (disabled)
+
 on:
-  pull_request:
-    types: [opened, synchronize]
+  workflow_dispatch:
+    inputs:
+      reason:
+        description: "Disabled — use understand-first-pr-analysis.yml"
+        required: false
+        default: "manual-only"
+
 jobs:
-  delta:
+  disabled:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
-        with:
-          python-version: '3.11'
-      - name: Install CLI
+      - name: Workflow disabled pending consolidation
         run: |
-          python -m pip install --upgrade pip
-          python -m pip install -e ".[dev,examples]"
-      - name: Build lens (base)
-        run: |
-          git fetch origin ${{ github.base_ref }} --depth=1 || true
-          git checkout -qf ${{ github.base_ref }} || true
-          u scan . -o maps/repo_base.json || true
-          u lens from-seeds --seed $(git ls-files | head -n 30) --map maps/repo_base.json -o maps/lens_base.json || true
-      - name: Build lens (head)
-        run: |
-          git checkout -qf ${{ github.sha }}
-          u scan . -o maps/repo_head.json || true
-          u lens from-seeds --seed $(git diff --name-only ${{ github.base_ref }} | tr '\n' ' ') --map maps/repo_head.json -o maps/lens_head.json || true
-      - name: Visualize delta
-        run: |
-          u visual delta maps/lens_base.json maps/lens_head.json -o maps/delta.svg || true
-      - name: Comment on PR with delta
-        uses: actions/github-script@v7
-        with:
-          script: |
-            const fs = require('fs');
-            let svg = ''; try { svg = fs.readFileSync('maps/delta.svg', 'utf8'); } catch(e) {}
-            const b64 = Buffer.from(svg).toString('base64');
-            const body = `### Understand-First Delta\n<img alt="delta" src="data:image/svg+xml;base64,${b64}" />`;
-            github.rest.issues.createComment({ ...context.repo, issue_number: context.issue.number, body });
+          echo "pr-delta-comment.yml is intentionally disabled."
+          echo "Use understand-first-pr-analysis.yml instead."
+          exit 0

.github/workflows/publish-pypi.yml

@@ -1,4 +1,5 @@
 name: Publish PyPI
+# Sole PyPI publisher (OIDC trusted publishing). Do not re-add twine upload in ci.yml.
 on:
   workflow_dispatch: {}
   release:

.github/workflows/release.yml

@@ -34,10 +34,11 @@ jobs:
           echo "" >> dist/RELEASE_NOTES.md
           echo "## VSIX SHA256" >> dist/RELEASE_NOTES.md
           cat dist/VSIX_SHA256.txt >> dist/RELEASE_NOTES.md
-      - name: Build understanding pack
+      - name: Build understanding pack (optional release asset)
+        continue-on-error: true
         run: |
           python -m pip install -e ".[dev,examples]"
-          u pack --publish || true
+          u pack publish
       - name: Upload artifacts
         uses: softprops/action-gh-release@v2
         with:

.github/workflows/tour-must-pass.yml

@@ -1,3 +1,5 @@
+# Fail-closed tour gate (Wave 3): critical scan/lens/trace/tour steps must succeed.
+# Soft-fail only optional gRPC codegen (HTTP server is required for hot_path).
 name: Tour Must Pass
 on:
   pull_request:
@@ -7,39 +9,78 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+
       - uses: actions/setup-python@v5
         with:
-          python-version: '3.11'
+          python-version: "3.11"
+
       - name: Install Python deps
         run: |
           python -m pip install --upgrade pip
           python -m pip install -e ".[dev,examples]"
+
       - name: Build repo map
         run: |
-          u scan . -o maps/repo.json || true
+          mkdir -p maps tours traces
+          u scan . -o maps/repo.json
+
       - name: Create lens from PR files
         run: |
-          CHANGED=$(git diff --name-only HEAD~1 | tr '\n' ' ')
-          u lens from-seeds --seed $CHANGED --map maps/repo.json -o maps/lens.json || true
+          CHANGED=$(git diff --name-only HEAD~1 2>/dev/null | tr '\n' ' ' || true)
+          if [ -z "$(echo "$CHANGED" | tr -d '[:space:]')" ]; then
+            CHANGED="examples/app/hot_path.py"
+          fi
+          u lens from-seeds --seed $CHANGED --map maps/repo.json -o maps/lens.json
+          test -f maps/lens.json
+
       - name: Generate gRPC Python code
+        continue-on-error: true
         run: |
-          python -m grpc_tools.protoc -I examples/apis             --python_out=examples/apis/gen             --grpc_python_out=examples/apis/gen             examples/apis/orders.proto
+          python -m grpc_tools.protoc -I examples/apis \
+            --python_out=examples/apis/gen \
+            --grpc_python_out=examples/apis/gen \
+            examples/apis/orders.proto
+
       - name: Start HTTP server
         run: |
           nohup python examples/servers/http_server.py >/tmp/http.log 2>&1 &
           sleep 2
+          curl -sf http://127.0.0.1:8000/pets >/dev/null
+
       - name: Start gRPC mock
+        continue-on-error: true
         run: |
           nohup python examples/servers/grpc_server.py >/tmp/grpc.log 2>&1 &
           sleep 2
+
       - name: Trace hot path (runtime truth)
         run: |
           u trace module examples/app/hot_path.py run_hot_path -o traces/tour.json
+          test -f traces/tour.json
           u lens merge-trace maps/lens.json traces/tour.json -o maps/lens_merged.json
+          test -f maps/lens_merged.json
+
       - name: Generate tour (from merged lens)
         run: |
-          u tour maps/lens_merged.json -o tours/PR.md || true
-      - name: Run tour (fixture)
+          u tour maps/lens_merged.json -o tours/PR.md
+          test -f tours/PR.md
+
+      - name: Run tour fixture (fail-closed gate)
         run: |
-          set -e
           u tour_run maps/lens_merged.json -f fixtures
+
+      - name: Upload tour artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: tour-must-pass-artifacts
+          path: |
+            maps/repo.json
+            maps/lens.json
+            maps/lens_merged.json
+            traces/tour.json
+            tours/PR.md
+          retention-days: 14
+          if-no-files-found: warn