chore(graphs): harden dual-graph tooling with pinned versions and fingerprint-based freshness

.codegraph/CODEGRAPH_REPORT.md

@@ -1,62 +1,40 @@
 # CodeGraph Report
 
-**Generated:** 2026-06-03T08:20:11.251Z
+Report schema: 1
+Source fingerprint: sha256:327ee3443156f26862b82a89db69efde7240173d4730246aee39df4f13539c56
+Tool: codegraph
+Tool version: 1.6.0
+Generation mode: local-index (codegraph status --json/files)
 
 ## Status
 
-```
-
-CodeGraph Status
-
-Project: /home/pc/StoryCraft-Studio
-
-Index Statistics:
-  Files:     959
-  Nodes:     9.358
-  Edges:     20.132
-  DB Size:   17.29 MB
-  Backend:   node:sqlite — built-in (full WAL)
-  Journal:   wal
-
-Nodes by Kind:
-  import          3.564
-  constant        1.571
-  function        1.527
-  file            942
-  method          795
-  interface       403
-  type_alias      257
-  variable        198
-  class           93
-  struct          6
-  enum            1
-  enum_member     1
-
-Files by Language:
-  typescript      605
-  tsx             304
-  javascript      23
-  yaml            17
-  rust            8
-  python          2
-
-✓ Index is up to date
-
-
+```text
+Initialized: yes
+Version: 1.6.0
+Files: 1407
+Nodes: 14945
+Edges: 55024
+Pending changes: {"added":0,"modified":0,"removed":0}
+Worktree mismatch: none
+Index built with: 1.6.0
+Reindex required: no
 ```
 
 ## Files by Extension
 
-- **.ts**: 605
-- **.tsx**: 304
-- **.mjs**: 17
-- **.yml**: 15
-- **.rs**: 8
+- **.ts**: 898
+- **.tsx**: 378
+- **.mjs**: 62
+- **.rs**: 21
+- **.mts**: 18
+- **.yml**: 18
 - **.js**: 4
+- **.yaml**: 3
 - **.cjs**: 2
-- **.yaml**: 2
 - **.py**: 2
+- **.xml**: 1
 
 ---
 
-*Regenerate with: `pnpm run codegraph:report`*
+*Regenerate with: `pnpm run graphs:report` (or `pnpm run codegraph:report` directly). Freshness
+check: `pnpm run graphs:status`. Package: worldscript-studio.*

.gitignore

@@ -72,9 +72,6 @@ features/**/*.html
 # Graphify — solo policy: only GRAPH_REPORT.md is committed; regenerate locally via pnpm run graphify:update
 graphify-out/*
 !graphify-out/GRAPH_REPORT.md
-graphify-out/cache/
-graphify-out/manifest.json
-graphify-out/cost.json
 
 # Runtime i18n: only bundle.json is deployed (sources live in locales/<lang>/)
 public/locales/*/*.json

.graphifyignore

@@ -15,6 +15,17 @@ playwright-report/
 # GraphiPy output (don't re-index the graph itself)
 graphify-out/
 
+# CodeGraph's own local index/DB — a second graph tool's runtime state, not source
+.codegraph/
+
+# Local tool config/metadata — never source
+.claude/
+.git/
+.git
+
+# Sibling git worktrees (defensive — this repo is itself checked out under .worktrees/main/)
+.worktrees/
+
 # Vendored/minified third-party bundles (not our source code; pollutes God Nodes/Communities)
 public/duckdb/
 

.vscode/tasks.json

@@ -64,6 +64,22 @@
       "problemMatcher": [],
       "presentation": { "reveal": "silent", "panel": "shared" },
       "group": { "kind": "build", "isDefault": false }
+    },
+    {
+      "label": "Dual-Graph: status (freshness check)",
+      "type": "npm",
+      "script": "graphs:status",
+      "problemMatcher": [],
+      "presentation": { "reveal": "always", "panel": "shared" },
+      "group": "none"
+    },
+    {
+      "label": "Dual-Graph: refresh + regenerate reports",
+      "type": "npm",
+      "script": "graphs:refresh",
+      "problemMatcher": [],
+      "presentation": { "reveal": "always", "panel": "shared" },
+      "group": { "kind": "build", "isDefault": false }
     }
   ]
 }

AUDIT.md

@@ -6,6 +6,8 @@
 
 **Release gate (2026-08-27 — v1.28.3):** Main CI/CD run `33113772841` (the push-triggered run for the release-prep merge commit) passed all applicable required and advisory jobs (Quality Gate Node 22+24, Tauri Rust Gate, Build, E2E, E2E Deep Coverage, Storybook, Lighthouse, Visual Regression, `CI Success`, `Deploy to GitHub Pages` — the last verified with a real `github-pages` Deployments API record for this exact commit, `state: success`); Core Rust Gate legitimately skipped (the release-prep commit touches `src-tauri/`, not `crates/`). CodeQL SAST run `33113772797` passed; 0 open code-scanning alerts. The tag-triggered Tauri workflow `33115805027` passed all 5 jobs (`Verify release tag`, `Bundle` for windows-latest/ubuntu-22.04/macos-latest, `GitHub Release`); the tag-triggered `CI / CD` run `33115805002` independently passed all applicable jobs including `E2E Tests (Playwright)` (`PR Size Governance` and `Deploy to GitHub Pages` legitimately skipped — restricted to `pull_request` and `refs/heads/main` respectively, neither of which a tag push satisfies) — no repeat of the non-deterministic tag-run E2E flake seen on v1.28.2's release. A parallel `Docker` workflow (`33115804967`) built and pushed `ghcr.io/qnbs/worldscript-studio` tagged `1.28.3`/`1.28`/`latest` (digest `sha256:b6e7d71b…`). The release publishes the same asset shape as v1.28.2: Linux x86_64 (rpm/deb/AppImage) and Windows x86_64 (msi/exe) artifacts with corresponding Minisign `.sig` files; macOS arm64 ships an unsigned `.dmg` installer plus a signed `.app.tar.gz` updater bundle (`.sig`) — no separate `.dmg.sig`; `latest.json` present; all 14 release assets uploaded successfully. Platform code-signing and notarization remain separate claims. No macOS x86_64 artifact, matching prior releases — Intel-macOS remains a gated qualification lane (ADR-0021). Landed via PR #530 (#527 fix — synchronous `isPortalActive` init + `isInitialLoad` guard on the bootstrap effect), PR #533 (E2E harness/precondition fix associated with #532 — `ensureWelcomePortalEntry()` deterministic startup-state precondition, including its own internal-reload-vs-autosave race and locale-independent WelcomePortal detection via a stable `data-testid`; #532's root cause stays open), and PR #534 (version bump + CHANGELOG/README release truth).
 
+**Dual-graph tooling revalidated (2026-08-28):** Graphify and CodeGraph were audited end-to-end and both upgraded under a `controlled-upgrade` policy — `graphifyy` 0.8.26 → 0.9.51, `@colbymchenry/codegraph` (last recorded here at 0.9.3, see the 2026-05-24 historical entry below) → 1.6.0. Both tools' tested versions are now tracked in one place, [`config/graph-tools-versions.json`](config/graph-tools-versions.json) — this file references it rather than recording a version number that would drift independently. The old 0.9.3 value is historical provenance, while 1.6.0 is the current tested upgrade target. Fixed: a committed `CODEGRAPH_REPORT.md` that had been generated inside an unrelated project with no live index behind it; a `dual-graph-update.mjs` that swallowed every failure and always printed a false success epilogue (replaced by `scripts/graphs-cli.mjs`'s explicit `doctor`/`status`/`update`/`report`/`refresh`/`bootstrap` interface); an orphaned, never-invoked pre-commit script; and commit-SHA-based freshness (unsafe under squash merge) in favor of a worktree-aware content fingerprint (`scripts/graphSourceFingerprint.mjs`). CodeGraph source/index processing remains local, but its default anonymous telemetry and separate update check are network-capable; use `codegraph telemetry off`, `CODEGRAPH_TELEMETRY=0`, `DO_NOT_TRACK=1`, and `CODEGRAPH_NO_UPDATE_CHECK=1` as local controls.
+
 **Release gate (2026-08-27 — v1.28.2):** Main CI/CD run `33064552219` passed all required and advisory jobs (Quality Gate Node 22+24, Tauri Rust Gate, Build, E2E, E2E Deep Coverage, Storybook, Lighthouse, Visual Regression, `CI Success`, `Deploy to GitHub Pages` — the last verified with real post-merge evidence, not just a green check: real `Set up job`/`Deploy to GitHub Pages`/`Complete job` steps and a genuine `github-pages` Deployments API record for this commit). Codecov project coverage 74.22% across 540 files. The tag-triggered Tauri workflow `33066539094` passed Ubuntu, Windows, and macOS bundle jobs plus GitHub Release generation and `latest.json`; a parallel `Docker` workflow built and pushed a container image to GHCR. The release publishes Linux x86_64 (rpm/deb/AppImage) and Windows x86_64 (msi/exe) artifacts with corresponding Minisign `.sig` files; macOS arm64 ships an unsigned `.dmg` installer plus a signed `.app.tar.gz` updater bundle (`.sig`) — no separate `.dmg.sig` is published; `latest.json` present. Platform code-signing and notarization remain separate claims. No macOS x86_64 artifact was available and it is omitted from the updater manifest, matching v1.28.1's pattern — Intel-macOS remains a gated qualification lane (ADR-0021), not yet in the production release matrix. Landed via PRs #519 (DA-06 docs truth), #520 (DA-05 DOCX export), #523 (#522 GitHub Pages deploy fix), and #524 (version bump + DA-03 gap fixes + the full onboarding-install-command doc-truth sweep). The separately-triggered tag CI/CD run (distinct from the main-push run above) hit a non-deterministic `tests/e2e/export.spec.ts` failure (`[Mobile Chrome]`, once also `[chromium]`) on the identical commit that passed cleanly on the main-push run; investigation ruled out cross-test/cross-run state persistence (ephemeral `ubuntu-latest` runners, fresh dev server and browser context per job/test) and traced it to a plausible pre-existing effect-ordering race between `hooks/useApp.ts`'s portal-activation effect and `App.tsx`'s auto-seed-blank-project effect, timing-sensitive rather than deterministic — filed as issue #527. Pre-existing and not introduced by v1.28.2. The published artifacts remain valid; the issue affects a timing-sensitive first-run/onboarding path present in the released code and is being addressed in a bounded follow-up intended for v1.28.3, not by amending v1.28.2. Fixed in v1.28.3 above via PR #530.
 
 **Release gate (2026-08-23 — v1.28.1):** Main CI/CD run `32616003387` passed all required and advisory jobs. The tag-triggered Tauri workflow `32616003394` passed Ubuntu, Windows, and macOS bundle jobs plus GitHub Release generation and `latest.json`. The release publishes Linux x86_64 (rpm/deb/AppImage), Windows x86_64 (msi/exe), and macOS arm64 (dmg/app.tar.gz) artifacts; platform code-signing and notarization remain separate claims. No macOS x86_64 artifact was available and it is omitted from the updater manifest, matching v1.28.0's pattern.

CLAUDE.md

@@ -347,7 +347,7 @@ Rules:
 - Before answering architecture or codebase questions, read `graphify-out/GRAPH_REPORT.md` for god nodes and community structure
 - If `graphify-out/wiki/index.md` exists, navigate it instead of reading raw files
 - For cross-module "how does X relate to Y" questions, prefer `graphify query "<question>"`, `graphify path "<A>" "<B>"`, or `graphify explain "<concept>"` over grep
-- After modifying code files in this session, run `pnpm run graphify:update` (AST-only, no API cost). First-time setup: `pnpm run graphify:bootstrap`.
+- After modifying code files in this session, run `pnpm run graphify:update` (AST-only, no API cost). First-time setup: `pnpm run graphify:bootstrap` (installs the exact version pinned in [`config/graph-tools-versions.json`](config/graph-tools-versions.json)). If in doubt whether the report is current, run `pnpm run graphs:status` first (FRESH/STALE, no mutation).
 
 ## codegraph
 
@@ -357,8 +357,9 @@ Rules:
 - Before answering code-structure, caller/callee, or impact questions, use CodeGraph MCP tools (`codegraph_context`, `codegraph_impact`, `codegraph_trace`)
 - If `.codegraph/` exists, answer directly with CodeGraph — don't delegate exploration to a file-reading sub-agent
 - For "how does X reach Y", use `codegraph_trace` instead of manual Grep + Read chains
-- After modifying code, the graph auto-syncs (2s debounce). For large refactors, run `pnpm run codegraph:update`
+- After modifying code, the graph auto-syncs via a file watcher (debounced). For routine manual updates use `pnpm run codegraph:sync` (incremental) — `pnpm run codegraph:update` is a full rebuild (`codegraph index --force`), for large refactors or index-corruption recovery, not routine use
 - To find affected tests: `pnpm run codegraph:affected`
+- First-time setup: `pnpm run codegraph:bootstrap` (installs the exact version pinned in [`config/graph-tools-versions.json`](config/graph-tools-versions.json)), then `codegraph init`
 
 ### Dual-Graph workflow
 - Architecture questions → `graphify-out/GRAPH_REPORT.md`

CONTRIBUTING.md

@@ -63,8 +63,8 @@ CodeGraph provides **semantic code intelligence** via MCP — symbol-level calle
 **Install:**
 
 ```bash
-npm install -g @colbymchenry/codegraph   # or pnpm add -g
-codegraph init -i                        # in repo root
+pnpm run codegraph:bootstrap              # installs the exact version pinned in config/graph-tools-versions.json
+pnpm run codegraph:init                   # in repo root; initializes the local index through the verified resolver
 ```
 
 **Agent setup (Kimi Code CLI):** add the MCP server to `~/.kimi/settings.json` (see `docs/codegraph.md` § MCP Integration).

README.md

@@ -13,7 +13,7 @@
   <img src="https://img.shields.io/badge/Storage-IndexedDB_v8-F59E0B" alt="IndexedDB v8">
   <img src="https://img.shields.io/badge/PWA-v3.0-5BB974?logo=pwa" alt="PWA v3.0">
   <img src="https://img.shields.io/badge/i18n-19_locales-2925_keys-0EA5E9" alt="i18n 19 locales — 2925 keys">
-  <img src="https://img.shields.io/badge/Tests-7219%2B_%2F_589_files-22C55E" alt="7219+ tests / 589 files">
+  <img src="https://img.shields.io/badge/Tests-7266%2B_%2F_591_files-22C55E" alt="7266+ tests / 591 files">
   <img src="https://img.shields.io/codecov/c/github/qnbs/WorldScript-Studio?logo=codecov&label=Coverage" alt="Codecov Coverage">
   <img src="https://img.shields.io/badge/License-MIT-22C55E" alt="License MIT">
   <img src="https://img.shields.io/github/actions/workflow/status/qnbs/WorldScript-Studio/.github/workflows/ci.yml?branch=main&logo=github" alt="CI Status">
@@ -511,7 +511,7 @@ The Settings → AI panel shows a live GPU status badge with adapter details and
 | **Document Export**  | docx + jszip                                              | Word-compatible `.docx` generation (lazy-loaded)                     |
 | **PWA**              | Service Worker + Web App Manifest v3                     | Offline support, installability, Workbox chunking                    |
 | **i18n**             | Custom React Context (`I18nContext.tsx`)                  | 2925 keys × 19 locales (de/en/es/fr/it + ar/he/fa RTL Beta + ja/zh/pt/el/fi/sv/hu/is/eu/ru/ko Beta); EN fallback; `localStorage` persistence |
-| **Testing**          | Vitest 4.x (7219+ tests / 589 files) + Playwright E2E     | Unit/integration + cross-browser E2E; Stryker mutation (manual workflow)          |
+| **Testing**          | Vitest 4.x (7266+ tests / 591 files) + Playwright E2E     | Unit/integration + cross-browser E2E; Stryker mutation (manual workflow)          |
 | **Code Quality**     | Biome (lint + format) + TypeScript 7 (tsgo) strict       | `--error-on-warnings` in CI; zero `any` policy                      |
 | **Visualization**    | Force-directed graph                                      | Interactive character relationship network                           |
 | **Desktop**          | Tauri v2                                                  | Cross-platform installer; auto-updater via `latest.json`             |
@@ -549,7 +549,7 @@ WorldScript-Studio/
 │   ├── sw.js             # PWA Service Worker
 │   └── manifest.json     # PWA Web App Manifest v3
 ├── tests/
-│   ├── unit/             # Vitest unit tests (7219+ tests, 589 files) — count spans tests/, components/, packages/*/tests/, not just this folder
+│   ├── unit/             # Vitest unit tests (7266+ tests, 591 files) — count spans tests/, components/, packages/*/tests/, not just this folder
 │   │   ├── ai/           # aiSmallModules, aiCoreFallbackPaths
 │   │   └── settings/     # WebLlmPanel, AiSections
 │   └── e2e/              # Playwright specs + helpers.ts
@@ -711,7 +711,7 @@ The main pipeline is [`.github/workflows/ci.yml`](.github/workflows/ci.yml). Opt
 | `scorecard`  | weekly + `main` push | OpenSSF Scorecard — SARIF uploaded to GitHub Code Scanning |
 
 **Current test metrics (2026-08-27, source-synchronized; CI remains authoritative for pass/fail):**
-- **7219+ unit tests** across **589 test files** — CI is authoritative for pass/fail
+- **7266+ unit tests** across **591 test files** — CI is authoritative for pass/fail
 - Coverage thresholds: lines ≥ 80 · branches ≥ 66 · functions ≥ 72 · statements ≥ 78 — enforced in CI (see Codecov badge for live metrics)
 - i18n: **2925 keys × 19 locales** (en/de/fr/es/it + ar/he/fa RTL Beta + ja/zh/pt/el/fi/sv/hu/is/eu/ru/ko Beta)
 

config/graph-tools-versions.json

@@ -0,0 +1,16 @@
+{
+  "schemaVersion": 1,
+  "graphifyy": {
+    "testedVersion": "0.9.51",
+    "policy": "controlled-upgrade",
+    "installedFrom": "0.8.26",
+    "notes": "v0.9.0 changed node-ID format (repo-relative path instead of parent-dir+filename); this repo uses no Neo4j/Gephi export, so the only effect is a one-time large diff in graphify-out/GRAPH_REPORT.md on the first graphify update . after upgrading. v0.9.13 fixed the query-log feature (introduced in v0.8.31, after this repo's prior pin) to default OFF; GRAPHIFY_QUERY_LOG_DISABLE=1 is a real, documented hard-off guarantee if ever needed."
+  },
+  "codegraph": {
+    "testedVersion": "1.6.0",
+    "policy": "controlled-upgrade",
+    "installedFrom": "1.1.3",
+    "notes": "Purely additive/corrective between 1.1.3 and 1.6.0 (no removed commands, no engines/dependency-shape change). Run a full `codegraph index` (not just sync) once immediately after upgrading -- several fixes require a re-index to take effect. Gains --no-color/NO_COLOR support (#1281, absent at 1.1.3) and CODEGRAPH_NO_UPDATE_CHECK=1 (#1243)."
+  },
+  "reportSchemaVersion": 1
+}