chore(sync): upstream develop @ e75445fc

.github/workflows/ci-zge.yml

@@ -0,0 +1,41 @@
+# ZGEnergy fork gates — required for main protection once registered as a check.
+name: ci-zge
+
+on:
+  pull_request:
+    branches: [main, develop]
+  push:
+    branches: [main, develop]
+  workflow_dispatch:
+
+concurrency:
+  group: ci-zge-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  zge-gates:
+    name: zge-gates
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22.22"
+          cache: npm
+
+      - name: Install
+        env:
+          ELECTRON_SKIP_BINARY_DOWNLOAD: "1"
+        run: |
+          npm ci || npm install --force
+
+      - name: Structural + focused tests + build
+        env:
+          ELECTRON_SKIP_BINARY_DOWNLOAD: "1"
+        run: |
+          chmod +x scripts/upstream-sync.sh
+          scripts/upstream-sync.sh verify

.github/workflows/publish.yml

@@ -289,6 +289,7 @@ jobs:
           # which enforces every non-private workspace appears here.
           PACKAGES=(
             "@blackbelt-technology/pi-dashboard-shared"
+            "@blackbelt-technology/pi-dashboard-bus-client"
             "@blackbelt-technology/pi-dashboard-extension"
             "@blackbelt-technology/pi-dashboard-server"
             "@blackbelt-technology/pi-dashboard-web"
@@ -302,6 +303,8 @@ jobs:
             "@blackbelt-technology/pi-dashboard-goal-plugin"
             "@blackbelt-technology/pi-dashboard-automation-plugin"
             "@blackbelt-technology/pi-image-fit-extension"
+            "@blackbelt-technology/pi-dashboard-nano-banana"
+            "@blackbelt-technology/pi-dashboard-video-production"
             "@blackbelt-technology/frontend-mockup-loop"
             "@blackbelt-technology/pi-dashboard-kb"
             "@blackbelt-technology/pi-dashboard-kb-extension"
@@ -311,6 +314,8 @@ jobs:
             "@blackbelt-technology/pi-dashboard-eng-disciplines"
             "@blackbelt-technology/pi-dashboard-authoring-toolkit"
             "@blackbelt-technology/pi-dashboard-video-transcription"
+            "@blackbelt-technology/pi-dashboard-session-distiller"
+            "@blackbelt-technology/pi-dashboard-distill-session-knowledge"
             "@blackbelt-technology/pi-agent-dashboard"
           )
           VERSION="${{ needs.resolve.outputs.version }}"

.github/workflows/upstream-sync.yml

@@ -0,0 +1,150 @@
+# Keep exactly one open upstream-sync PR: stable branch force-updated each run.
+name: upstream-sync
+
+on:
+  schedule:
+    # Mondays 15:00 UTC
+    - cron: "0 15 * * 1"
+  workflow_dispatch:
+    inputs:
+      upstream_ref:
+        description: Upstream branch to merge
+        required: false
+        default: develop
+      dry_run:
+        description: If true, only print status
+        required: false
+        default: "false"
+
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: upstream-sync
+  cancel-in-progress: false
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    env:
+      UPSTREAM_REF: ${{ github.event.inputs.upstream_ref || 'develop' }}
+      GH_REPO: ${{ github.repository }}
+      # Stable branch — each run force-with-lease updates the same PR head
+      SYNC_BRANCH: sync/upstream-${{ github.event.inputs.upstream_ref || 'develop' }}
+    steps:
+      - name: Checkout main
+        uses: actions/checkout@v4
+        with:
+          ref: main
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Configure git identity
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - name: Add upstream remote
+        run: |
+          git remote add upstream https://github.com/BlackBeltTechnology/pi-agent-dashboard.git \
+            || git remote set-url upstream https://github.com/BlackBeltTechnology/pi-agent-dashboard.git
+          git fetch upstream "$UPSTREAM_REF" --prune
+          git fetch origin main --prune
+
+      - name: Status
+        id: status
+        run: |
+          chmod +x scripts/upstream-sync.sh
+          scripts/upstream-sync.sh status | tee /tmp/upstream-status.txt
+          BEHIND=$(git rev-list --count "origin/main..upstream/${UPSTREAM_REF}")
+          echo "behind=$BEHIND" >> "$GITHUB_OUTPUT"
+          SHA=$(git rev-parse --short "upstream/${UPSTREAM_REF}")
+          echo "usha=$SHA" >> "$GITHUB_OUTPUT"
+
+      - name: Skip if up to date
+        if: steps.status.outputs.behind == '0'
+        run: echo "Already up to date with upstream."
+
+      - name: Dry run only
+        if: github.event_name == 'workflow_dispatch' && github.event.inputs.dry_run == 'true'
+        run: echo "dry_run=true; stopping before merge"
+
+      - name: Merge + upsert single PR
+        if: steps.status.outputs.behind != '0' && !(github.event_name == 'workflow_dispatch' && github.event.inputs.dry_run == 'true')
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set +e
+          scripts/upstream-sync.sh merge
+          rc=$?
+          set -e
+          echo "merge_rc=$rc"
+          if [[ $rc -eq 0 ]]; then
+            scripts/upstream-sync.sh pr
+            exit 0
+          fi
+          if [[ $rc -ne 2 ]]; then
+            exit $rc
+          fi
+
+          # Conflicts remain: publish help on the same stable branch (still one PR),
+          # close any other sync PRs, leave draft for human/agent resolution.
+          REPORT=$(ls docs/upstream-sync-conflicts-*.md 2>/dev/null | head -1 || true)
+          git merge --abort || true
+          git checkout -B "$SYNC_BRANCH" origin/main
+          mkdir -p docs
+          {
+            echo "# Upstream sync needs human/agent merge"
+            echo
+            echo "Upstream \\\`${UPSTREAM_REF}\\` @ \\\`${{ steps.status.outputs.usha }}\\` is **${{ steps.status.outputs.behind }}** commits ahead of main."
+            echo
+            echo "Automation keeps **one** open PR on \\\`${SYNC_BRANCH}\\` (this branch is force-updated)."
+            echo
+            echo "Resolve with:"
+            echo
+            echo '```bash'
+            echo "git fetch upstream && scripts/upstream-sync.sh merge"
+            echo "# resolve remaining paths, then:"
+            echo "scripts/upstream-sync.sh verify && scripts/upstream-sync.sh pr"
+            echo '```'
+            echo
+            if [[ -n "$REPORT" && -f "$REPORT" ]]; then
+              echo "## Conflict inventory"
+              echo
+              cat "$REPORT"
+            fi
+          } > docs/upstream-sync-help.md
+          git add docs/upstream-sync-help.md
+          if [[ -n "$REPORT" && -f "$REPORT" ]]; then git add "$REPORT" || true; fi
+          git commit -m "chore(sync): conflict help for ${UPSTREAM_REF}@${{ steps.status.outputs.usha }}"
+          git push --force-with-lease -u origin "$SYNC_BRANCH"
+
+          # Close other sync PRs; upsert this one as draft
+          KEEP_HEAD="$SYNC_BRANCH" GH_REPO_VAL="$GH_REPO" python3 - <<'PY'
+import json, os, subprocess
+repo = os.environ["GH_REPO_VAL"]
+keep = os.environ["KEEP_HEAD"]
+raw = subprocess.check_output(["gh","pr","list","-R",repo,"--state","open","--limit","100","--json","number,headRefName,labels"], text=True)
+for pr in json.loads(raw):
+    head = pr.get("headRefName") or ""
+    labels = {(l.get("name") if isinstance(l, dict) else l) for l in (pr.get("labels") or [])}
+    if head == keep:
+        continue
+    if not head.startswith("sync/upstream"):
+        continue
+    n = str(pr["number"])
+    body = f"Superseded by latest automated sync on `{keep}`."
+    subprocess.run(["gh","pr","close",n,"-R",repo,"--comment",body], check=False)
+PY
+
+          existing=$(gh pr list -R "$GH_REPO" --state open --head "$SYNC_BRANCH" --json number --jq '.[0].number // empty' || true)
+          TITLE="chore(sync): CONFLICTS upstream ${UPSTREAM_REF} @ ${{ steps.status.outputs.usha }}"
+          if [[ -n "$existing" ]]; then
+            gh pr edit "$existing" -R "$GH_REPO" --title "$TITLE" --body-file docs/upstream-sync-help.md || true
+            gh pr ready "$existing" -R "$GH_REPO" --undo 2>/dev/null || true
+          else
+            gh pr create -R "$GH_REPO" --base main --head "$SYNC_BRANCH" --draft \
+              --title "$TITLE" --label upstream-sync --body-file docs/upstream-sync-help.md
+          fi

.pi/settings.json

@@ -8,10 +8,10 @@
     }
   ],
   "worktreeInit": {
-    "gate": "test ! -d node_modules || test ! -d .pi/skills/openspec-explore || test ! -f .pi/dashboard/kb/index.db",
+    "gate": "test ! -e node_modules/.package-lock.json || test ! -d .pi/skills/openspec-explore || test ! -f .pi/dashboard/kb/index.db",
     "run": {
       "type": "script",
-      "command": "npm ci && npx openspec init --tools pi --force && npm run build --workspace=@blackbelt-technology/pi-dashboard-kb && NODE_OPTIONS=--experimental-sqlite npx kb index"
+      "command": "(npm ci || npm install) && npx @fission-ai/openspec init --tools pi --force && npm run build --workspace=@blackbelt-technology/pi-dashboard-kb && NODE_OPTIONS=--experimental-sqlite npx kb index"
     }
   }
 }

.pi/skills/AGENTS.md

@@ -18,7 +18,8 @@ Files in this directory. One row per file. Non-source area (migrated from `docs/
 | `code-review/references/` | Language guides + architecture/performance/security review references |
 | `code-review/SKILL.md` | Skill: comprehensive code review with severity labels |
 | `component-architecture/SKILL.md` | Reusable component patterns: folder structure (`ui/layout/sections/cards/forms/shared/seo`),… → see `component-architecture/SKILL.md.AGENTS.md` |
-| `debug-dashboard/references/known-issues.md` | Known-issue catalogue distilled from `docs/faq.md`: server won't start (Electron Node bin fallback… → see `debug-dashboard/references/known-issues.md.AGENTS.md` |
+| `debug-dashboard/references/isolated-verification.md` | Isolated UI/worktree verification. Live :8000 runs MAIN-repo code; `npm run build` leaks to `packages/client/dist`. Temp HOME + non-8000 ports + `PI_DASHBOARD_NO_MDNS=1`. Mockup-serve + worktree-harness recipe. |
+| `debug-dashboard/references/known-issues.md` | Known-issue catalogue distilled from `docs/faq.md`: server won't start (Electron Node bin fallback… + new-session spawn_register_timeout (pi-crash vs overload split) → see `debug-dashboard/references/known-issues.md.AGENTS.md` |
 | `debug-dashboard/references/log-locations.md` | Persistent file map. `~/.pi/dashboard/`: `server.log` (append, timestamped banners, grep recipes),… → see `debug-dashboard/references/log-locations.md.AGENTS.md` |
 | `debug-dashboard/references/test-failure-triage.md` | Vitest failure triage. Golden rule tee→grep (`npm test 2>&1 | tee /tmp/pi-test.log`), standard greps,… → see `debug-dashboard/references/test-failure-triage.md.AGENTS.md` |
 | `debug-dashboard/references/ui-debug.md` | Pointer to `browser` skill for UI/visual debugging. Symptom routing table:… → see `debug-dashboard/references/ui-debug.md.AGENTS.md` |
@@ -31,6 +32,8 @@ Files in this directory. One row per file. Non-source area (migrated from `docs/
 | `document-converter/SKILL.md` | NL-triggered document conversion. Ingest PDF/DOCX/PPTX/XLSX→md for kb; produce md→DOCX/PDF templated. Routes to packages/document-converter facade. See change: document-converter. |
 | `edit-flow/SKILL.md` | Skill: create/edit pi-flows flows + agents via `flow_agents` + `flow_write`. → see `edit-flow/SKILL.md.AGENTS.md` |
 | `faq-mine/SKILL.md` | Skill: mine `docs/faq.md` from README.md + evergreen `docs/*.md`. → see `faq-mine/SKILL.md.AGENTS.md` |
+| `fix-worktree-opsx-skills-not-created/SKILL.md` | Skill. Fix worktree missing generated openspec-* (opsx) skills. `worktreeInit` must call `npx @fission-ai/openspec init`; bare `openspec` = squatted 0.0.0 npm stub that inits nothing. |
+| `frontend-mockup-loop-dashboard/SKILL.md` | Skill. Dashboard adapter over frontend-mockup-loop. Binds 7-step loop to `packages/client` sources, theme-system tokens (4 themes), isolated-verification, `openspec/changes/<name>/mockups/`. |
 | `implement/references/code-discipline.md` | Reference: expands AGENTS.md "Code Instructions" 5 rules with worked examples. → see `implement/references/code-discipline.md.AGENTS.md` |
 | `implement/references/rebuild-matrix.md` | Reference: full 3-component rebuild matrix. Per-component recipes — extension `npm run… → see `implement/references/rebuild-matrix.md.AGENTS.md` |
 | `implement/scripts/check-mode.ts` | Print dashboard mode ("dev"/"production") via `GET /api/health`. → see `implement/scripts/check-mode.ts.AGENTS.md` |
@@ -88,13 +91,16 @@ Files in this directory. One row per file. Non-source area (migrated from `docs/
 | `pi-dashboard/references/slash-commands.md` | Reference catalog of every `/dashboard:*` slash command with args and LLM-free vs LLM-bound classification. Naming grammar `/dashboard:<resource>-<verb>[-<modifier>]`. |
 | `pi-dashboard/scripts/dashboard-api.sh` | Helper script with port auto-detection + auth |
 | `pi-dashboard/SKILL.md` | Bundled skill: monitor + control dashboard from any pi session. → see `pi-dashboard/SKILL.md.AGENTS.md` |
+| `plan-proposal/SKILL.md` | Develop-side planning orchestrator. Chains artifact-gen (openspec-new/-ff/-continue) → doubt-driven-review on proposal.md/design.md (ARTIFACT+CONTRACT only, cross-model offer) → scenario-design → category-routed fold of `automated` manifest scenarios into vanilla `tasks.md` checkboxes (harness-exemplar pointer + Triple; no custom token). Main-session-only (refuses subagent: nested reviewer + ask_user gate). Stops at worktree boundary; hands to ship-it. See change: add-openspec-pipeline-orchestrators. |
+| `pre-scaffold-openspec-coherence-check/SKILL.md` | Skill. Pre-scaffold checks before new openspec change: archive sweep, active sweep, current-code verify, slot-props contract, registry check. Avoid re-proposing archived work. |
 | `release-cut/SKILL.md` | Cuts new release: promotes `## [Unreleased]` in CHANGELOG → dated section, bumps every workspace… → see `release-cut/SKILL.md.AGENTS.md` |
 | `release-revoke/SKILL.md` | `release-revoke` skill. Reverts a release: deletes GitHub Release, removes git tag (local + origin), `npm… → see `release-revoke/SKILL.md.AGENTS.md` |
 | `responsive-mobile-first/SKILL.md` | Mobile-first responsive patterns: sticky headers, mobile drawer, floating CTA, responsive grids, touch… → see `responsive-mobile-first/SKILL.md.AGENTS.md` |
-| `scenario-design/references/technique-cheatsheet.md` | How-to per design/resilience technique with repo examples. EP: split input classes (invalid too). → see `scenario-design/references/technique-cheatsheet.md.AGENTS.md` |
-| `scenario-design/references/test-plan-schema.md` | Exact `test-plan.md` layout. Header: stage + generated date. Soft-gate clarification banner. → see `scenario-design/references/test-plan-schema.md.AGENTS.md` |
-| `scenario-design/SKILL.md` | Drafts adversarial real-life test scenarios from OpenSpec change spec. → see `scenario-design/SKILL.md.AGENTS.md` |
-| `ship-change/SKILL.md` | End-to-end "land it" pipeline after openspec-apply. Base branch `develop`, worktree `.worktrees/os-<change>`… → see `ship-change/SKILL.md.AGENTS.md` |
+| `run-dashboard-e2e-local-changes/SKILL.md` | Skill. Run Playwright E2E vs `docker/` harness reflecting LOCAL changes. `docker compose -f docker/compose.yml build` FIRST (test-up.sh omits `--build`). Seed env `PI_E2E_SEED=1`. |
+| `ship-change/SKILL.md` | End-to-end "land it" pipeline after openspec-apply. Base branch `develop`, worktree `.worktrees/os-<change>`… Step 1 defer rule now manifest-aware: `test-plan.md` present → defer only `manual-only` rows (via `deferDecision` in ship-it/scripts/manifest.ts); absent → legacy keyword defer verbatim. Step 10 teardown-before-worktree-removal ordering contract with ship-it. → see `ship-change/SKILL.md.AGENTS.md`. See change: add-openspec-pipeline-orchestrators |
+| `ship-it/scripts/manifest.ts` | Pure ship-it/ship-change manifest helpers (unit-tested). `parseManifest(text)` → `{id,level,disposition}[]` from test-plan.md tables (tolerant of malformed/no-disposition). `classifyTaskDisposition(task,map)`. `deferDecision(tasks,manifestText\|null)` → defer/stop (manifest: only manual-only defers; no manifest: legacy keyword). `filesystemRealityCheck(scenarios,exists)` → automated satisfied only if test file exists. See change: add-openspec-pipeline-orchestrators. |
+| `ship-it/scripts/no-weakening.ts` | Pure `assertNoWeakening(diff)` → `{ok,reasons}`. Parses unified test-file diff; rejects added `.only`/skip, net assertion deletion (expect() removed>added), strong→permissive matcher swap; allows genuine value-change fix. Enforced each ship-it red-test fix cycle. See change: add-openspec-pipeline-orchestrators. |
+| `ship-it/SKILL.md` | Worktree-side implementation orchestrator (headless-capable). Idempotent: gates `automated` scenarios on filesystem-reality (test file exists + harness-green), not the tasks.md checkbox. Owns red-test fix loop (never re-invokes apply on checked task; progress-bound; no-weakening guardrail via scripts/no-weakening.ts). Harness via docker/test-up.sh, port from `.pi-test-harness.json` `dashboardPort` (never `:18000`), trap always-teardown. Drives ship-change inline, manifest-aware defer, teardown before worktree removal. Escape hatch → SHIP_IT_BLOCKED.md, exit non-zero. See change: add-openspec-pipeline-orchestrators. |
 | `spec-coherence-check/references/proposal-queue-schema.md` | JSON schema for `.pi/proposal-queue.json` |
 | `spec-coherence-check/SKILL.md` | Skill: sweep proposals for staleness, conflicts, obsolescence against codebase |
 | `switch-extension-source/scripts/switch-source.ts` | Toggle script. Commands: status \| local <pkg> [--overlay] \| npm <pkg>. <pkg> = monorepo dir or npm name. → see `switch-extension-source/scripts/switch-source.ts.AGENTS.md` |

.pi/skills/debug-dashboard/SKILL.md

@@ -48,6 +48,7 @@ If `health-probe` says "not-running" → server isn't up. Check `server.log` for
 | `EADDRINUSE` on start | Concurrent spawn from multiple pi sessions | Harmless — losing process exits silently. Check log. |
 | Bridge connects then disconnects | `server_restarting` broadcast active, or version skew | grep `server_restarting` in server.log; check `/api/health` for version |
 | Blank page in browser | Vite not running in dev mode (silent fallback to prod build); or auth blocking | Check `/api/health.mode`; check `auth` settings |
+| New session won't start / yellow `spawn_register_timeout`, no card | `pi` crashed at startup (bad extension) OR host overload | See `references/known-issues.md` → "New session won't start" — manual `pi --mode rpc` run splits crash vs overload |
 | `Cannot connect to dashboard server` on Electron boot | `launchDashboardServer` fell back to `process.execPath` (Electron GUI binary) | See `references/known-issues.md` → "Electron Node bin selection" |
 | Fastify crashes immediately | Bad Node version (22.0–22.17.x or 24.1–24.2.x per nodejs/node#58515) | `node --version` — must be ≥ 22.18.0 |
 
@@ -75,6 +76,10 @@ Patterns + per-package vitest configs + watch mode are documented in [`reference
 
 This skill stops at "the server says X but the UI shows Y". For visual debugging — verifying layouts, screenshotting, hunting console errors, testing responsive breakpoints — switch to the **`browser`** skill (shipped by the dashboard bridge extension to every session). Quick pointer: see [`references/ui-debug.md`](references/ui-debug.md).
 
+## When you must verify a change without touching the live server
+
+The live `:8000` server runs MAIN-repo code — `/api/restart` never loads worktree edits, and a careless `npm run build` **leaks** into `packages/client/dist` (what live serves). To verify a UI/worktree change or serve a review mockup in full isolation (temp `HOME`, non-8000 ports, `PI_DASHBOARD_NO_MDNS=1`), see [`references/isolated-verification.md`](references/isolated-verification.md).
+
 ## Log file locations
 
 All log + config files. Worth bookmarking. See [`references/log-locations.md`](references/log-locations.md) for the full map.