Push model

.claude/skills/dev-dispatch/SKILL.md

@@ -5,7 +5,9 @@ disable-model-invocation: true
 argument-hint: "[--light] [task description or context]"
 ---
 
-You are executing the **dev-dispatch** workflow for **graphrefly-ts** (GraphReFly TypeScript implementation).
+You are executing the **dev-dispatch** workflow for **GraphReFly** (cross-language: TypeScript + Python).
+
+Operational docs, roadmap, optimizations, and skills all live in **graphrefly-ts** (this repo). Implementation may target `graphrefly-ts`, `graphrefly-py` (`~/src/graphrefly-py`), or both.
 
 The user's task/context is: $ARGUMENTS
 
@@ -26,8 +28,8 @@ Read in parallel:
 - `docs/test-guidance.md` — checklist for the relevant layer (core protocol, node, graph, extra)
 - `docs/roadmap.md` — if this is a new feature or cross-cutting change (active/open items only; completed phases archived to `archive/roadmap/*.jsonl`)
 - Any files the user referenced in $ARGUMENTS
-- Relevant source files in the area you'll modify
-- Existing tests for the area
+- Relevant source files in the area you'll modify (TS: `src/`, PY: `~/src/graphrefly-py/src/graphrefly/`)
+- Existing tests for the area (TS: `src/__tests__/`, PY: `~/src/graphrefly-py/tests/`)
 
 **Mandatory for patterns/ work:** If the task touches any file in `src/patterns/` or `src/compat/`, reading `~/src/graphrefly/COMPOSITION-GUIDE.md` is **mandatory**, not optional. The harness, orchestration, messaging, and all Phase 4+ code are composed factories — modifying their tests or implementation requires understanding composition patterns (lazy activation, subscription ordering, feedback cycles, SENTINEL gate).
 
@@ -40,11 +42,13 @@ While planning, explicitly validate proposed changes against these invariants (f
 - **Unknown message types forward** — do not swallow unrecognized tuples.
 - Prefer **composition (nodes + edges)** over monolithic configuration objects.
 - For **diamond** topologies, recomputation happens once per upstream change after all deps settle.
-- **No polling** — never poll node values on a timer or busy-wait. Use reactive sources (`fromTimer`, `fromCron`) instead (spec §5.8).
-- **No imperative triggers** — no event emitters, callbacks, or `setTimeout` + `set()` workarounds. All coordination uses reactive `NodeInput` signals (spec §5.9).
-- **No raw Promises or microtasks** — no bare `Promise`, `queueMicrotask`, `setTimeout`, or `process.nextTick` for reactive work. Async belongs in sources and the runner layer (spec §5.10).
-- **Central timer and `messageTier`** — use `core/clock.ts` for timestamps, `messageTier` for tier classification. Never hardcode type checks (spec §5.11).
+- **No polling** — never poll node values on a timer or busy-wait. Use reactive sources (`fromTimer`/`from_timer`, `fromCron`/`from_cron`) instead (spec §5.8).
+- **No imperative triggers** — no event emitters, callbacks, or `setTimeout`/`threading.Timer` + `set()` workarounds. All coordination uses reactive `NodeInput` signals (spec §5.9).
+- **No raw async primitives** — TS: no bare `Promise`, `queueMicrotask`, `setTimeout`, `process.nextTick`. PY: no bare `asyncio.ensure_future`, `asyncio.create_task`, `threading.Timer`, or raw coroutines. Async belongs in sources and the runner layer (spec §5.10).
+- **Central timer and `messageTier`/`message_tier`** — TS: use `core/clock.ts`. PY: use `core/clock.py`. Never hardcode type checks (spec §5.11).
 - **Phase 4+ APIs must be developer-friendly** — sensible defaults, minimal boilerplate, clear errors. Protocol internals never surface in primary APIs (spec §5.12).
+- **PY: Thread safety** — design for GIL and free-threaded Python where core APIs are documented as thread-safe. Per-subgraph `RLock` (see roadmap Phase 0.4).
+- **PY: No `async def` in public APIs** — all public functions return `Node[T]`, `Graph`, `None`, or a plain synchronous value.
 
 Do NOT start implementing yet.
 
@@ -66,12 +70,13 @@ Do NOT start implementing yet.
 Prioritize (in order):
 1. **Correctness** — matches `~/src/graphrefly/GRAPHREFLY-SPEC.md` and protocol invariants
 2. **Completeness** — edge cases (errors, completion, reconnect, diamonds)
-3. **Consistency** — matches patterns already in graphrefly-ts
+3. **Consistency** — matches patterns already in the target repo
 4. **Simplicity** — minimal solution
+5. **Thread safety** (PY) — where concurrent `get()` / propagation applies
 
 Do NOT consider backward compatibility at this early stage (pre-1.0).
 
-**Cross-language decision log:** If Phase 1–2 surface an **architectural or product-level** question (protocol semantics, batch/node invariants, parity between ports, or anything that needs a spec/product call), **jot it down** in **`docs/optimizations.md`** under **"Active work items"**. If the sibling repo **`graphrefly-py`** is available, add a **matching** entry to **`graphrefly-py/docs/optimizations.md`** so both implementations stay visible. If the sibling tree is not in the workspace, tell the user to mirror the note there. When the decision is **resolved**, move it to `archive/optimizations/resolved-decisions.jsonl` per `docs/docs-guidance.md` § "Optimization decision log".
+**Cross-language decision log:** If Phase 1–2 surface an **architectural or product-level** question (protocol semantics, batch/node invariants, parity between ports, or anything that needs a spec/product call), **jot it down** in **`docs/optimizations.md`** under **"Active work items"** (this repo is the single source of truth for both TS and PY). When the decision is **resolved**, move it to `archive/optimizations/resolved-decisions.jsonl` per `docs/docs-guidance.md` § "Optimization decision log".
 
 **Wait for user approval before proceeding.**
 
@@ -96,9 +101,11 @@ After user approves (full mode) or after Phase 1 (light mode, no escalation):
 2. Create tests following `docs/test-guidance.md`:
    - Put tests in the most specific existing file under `src/__tests__/` (or colocated `*.test.ts` per project convention)
    - Use **`Graph.observe()`** / **`graph.observe()`** for live message assertions when the Graph API exists; until then, test at the **node** and **message** level per test-guidance
-3. Run tests: `pnpm test`
-4. Fix any test failures
+3. Run checks:
+   - **TS:** `pnpm test`
+   - **PY:** `cd ~/src/graphrefly-py && uv run pytest && uv run ruff check src/ tests/ && uv run mypy src/`
+4. Fix any failures
 
-If implementation leaves an **open architectural decision** (deferred behavior, parity caveat, or “needs spec” item), add it to **`docs/optimizations.md`** under “Active work items” and mirror to **`graphrefly-py/docs/optimizations.md`** when that repo is available. When resolved, archive to `archive/optimizations/resolved-decisions.jsonl` per `docs/docs-guidance.md`.
+If implementation leaves an **open architectural decision** (deferred behavior, parity caveat, or “needs spec” item), add it to **`docs/optimizations.md`** under “Active work items” (this repo is the single source of truth). When resolved, archive to `archive/optimizations/resolved-decisions.jsonl` per `docs/docs-guidance.md`.
 
 When done, briefly list files changed and new exports added. Then suggest running `/qa` for adversarial review and final checks.

.claude/skills/parity/SKILL.md

@@ -7,6 +7,8 @@ argument-hint: "[feature area or 'full'] [optional: path to sibling repo]"
 
 You are executing the **parity** workflow, comparing **graphrefly-ts** (this repo) against **graphrefly-py** (`~/src/graphrefly-py` unless overridden in $ARGUMENTS).
 
+**This repo is the single source of truth** for all operational docs (roadmap, optimizations, test-guidance, docs-guidance, archive). Both repos' docs are maintained here.
+
 Context from user: $ARGUMENTS
 
 ---
@@ -18,11 +20,10 @@ Determine scope from $ARGUMENTS:
 - If `full`, scan all implemented phases in both roadmaps.
 
 Read in parallel:
-- **This repo:** `docs/optimizations.md` (active items + deferred), `archive/optimizations/*.jsonl` (cross-language notes, resolved decisions — search with `grep`), `docs/roadmap.md` (active/open items only; completed phases archived to `archive/roadmap/*.jsonl`), `~/src/graphrefly/GRAPHREFLY-SPEC.md` (relevant sections)
-- **Sibling repo:** `~/src/graphrefly-py/docs/optimizations.md`, `~/src/graphrefly-py/archive/optimizations/*.jsonl`, `~/src/graphrefly-py/docs/roadmap.md` (active/open items only; completed phases archived to `archive/roadmap/*.jsonl`)
+- **Operational docs (this repo):** `docs/optimizations.md` (active items + deferred), `archive/optimizations/*.jsonl` (cross-language notes, resolved decisions — search with `grep`), `docs/roadmap.md` (active/open items only; completed phases archived to `archive/roadmap/*.jsonl`), `~/src/graphrefly/GRAPHREFLY-SPEC.md` (relevant sections)
 - **Composition guide:** `~/src/graphrefly/COMPOSITION-GUIDE.md` — **mandatory** when the scoped area includes `src/patterns/` or `src/compat/` in either repo. Composed factories require understanding lazy activation, subscription ordering, null guards, wiring order, feedback cycles, and SENTINEL gate patterns.
-- Source files in the scoped area from **both** repos
-- Test files in the scoped area from **both** repos
+- **TS source:** `src/` and `src/__tests__/` in the scoped area
+- **PY source:** `~/src/graphrefly-py/src/graphrefly/` and `~/src/graphrefly-py/tests/` in the scoped area
 
 **Important:** Read `archive/optimizations/cross-language-notes.jsonl` entries with `id` prefix `divergence-`. These are **confirmed intentional divergences** — do NOT re-raise them as parity gaps or QA findings. Filter them out before presenting results.
 
@@ -121,7 +122,10 @@ After user approves:
    - Run `cd ~/src/graphrefly-py && uv run pytest` — fix failures
 4. Update `docs/optimizations.md` in **both** repos:
    - Add new open decisions under "Active work items"
-   - When decisions are resolved, archive to `archive/optimizations/resolved-decisions.jsonl` per `docs/docs-guidance.md` § "Optimization decision log"
+   - **Actively sweep:** scan for any fully-resolved items (all sub-tasks DONE, no remaining TODOs) and archive them to `archive/optimizations/resolved-decisions.jsonl` per `docs/docs-guidance.md` § "Optimization decision log". Remove archived content from `optimizations.md`.
+5. Update `docs/roadmap.md`:
+   - Check off completed items
+   - **Actively sweep:** scan for any fully-completed phase or item group and archive to `archive/roadmap/*.jsonl` per `docs/docs-guidance.md` § "Roadmap archive". Remove archived content from `roadmap.md`.
 
 ---
 

.claude/skills/qa/SKILL.md

@@ -5,7 +5,9 @@ disable-model-invocation: true
 argument-hint: "[--skip-docs] [optional context about what was implemented]"
 ---
 
-You are executing the **qa** workflow for **graphrefly-ts** (GraphReFly TypeScript implementation).
+You are executing the **qa** workflow for **GraphReFly** (cross-language: TypeScript + Python).
+
+Operational docs live in **graphrefly-ts** (this repo). The diff may include changes in `graphrefly-ts` and/or `graphrefly-py` (`~/src/graphrefly-py`).
 
 Context from user: $ARGUMENTS
 
@@ -26,10 +28,10 @@ Run `git diff` to get all uncommitted changes. If there are also untracked files
 Launch these as parallel Agent calls. Each receives the diff and the context from $ARGUMENTS (what was implemented and why).
 
 **Subagent 1: Blind Hunter** — Pure code review, no project context:
-> You are a Blind Hunter code reviewer. Review this diff for: logic errors, off-by-one errors, race conditions, resource leaks, missing error handling, security issues, dead code, unreachable branches. Output each finding as: **title** | **severity** (critical/major/minor) | **location** (file:line) | **detail**. Be adversarial — assume bugs exist.
+> You are a Blind Hunter code reviewer. Review this diff for: logic errors, off-by-one errors, race conditions, resource leaks, missing error handling, security issues, dead code, unreachable branches. For Python code, also check thread safety (including free-threaded Python without GIL). Output each finding as: **title** | **severity** (critical/major/minor) | **location** (file:line) | **detail**. Be adversarial — assume bugs exist.
 
 **Subagent 2: Edge Case Hunter** — Has project read access:
-> You are an Edge Case Hunter. Review this diff in the context of **GraphReFly** (`~/src/graphrefly/GRAPHREFLY-SPEC.md`). First, read `archive/optimizations/cross-language-notes.jsonl` and collect all entries with `id` prefix `divergence-` — these are **confirmed intentional cross-language divergences** that must NOT be raised as findings. Then check: unhandled message sequences (DIRTY without follow-up, DATA vs RESOLVED), diamond resolution (recompute once), COMPLETE/ERROR terminal rules, forward-unknown-types, batch semantics (DATA deferred, DIRTY not), reconnect/teardown leaks, meta companion nodes, and graph mount/signal propagation when `Graph` is in scope. Also flag violations of design invariants (spec §5.8–5.12): polling patterns (busy-wait or setInterval on node values), imperative triggers bypassing graph topology, bare Promises/queueMicrotask/setTimeout for reactive scheduling, direct Date.now()/performance.now() usage (must use core/clock.ts), hardcoded message type checks instead of messageTier utilities, and Phase 4+ APIs that leak protocol internals (DIRTY/RESOLVED/bitmask) into their primary surface. **If the change touches `src/patterns/` or `src/compat/`, verify the implementation against COMPOSITION-GUIDE.md categories (§1 lazy activation, §2 subscription ordering, §3 null guards, §5 wiring order, §7 feedback cycles, §8 SENTINEL gate).** For each finding: **title** | **trigger_condition** | **potential_consequence** | **location** | **suggested_guard**.
+> You are an Edge Case Hunter. Review this diff in the context of **GraphReFly** (`~/src/graphrefly/GRAPHREFLY-SPEC.md`). First, read `archive/optimizations/cross-language-notes.jsonl` and collect all entries with `id` prefix `divergence-` — these are **confirmed intentional cross-language divergences** that must NOT be raised as findings. Then check: unhandled message sequences (DIRTY without follow-up, DATA vs RESOLVED), diamond resolution (recompute once), COMPLETE/ERROR terminal rules, forward-unknown-types, batch semantics (DATA deferred, DIRTY not), reconnect/teardown leaks, meta companion nodes, and graph mount/signal propagation when `Graph` is in scope. Also flag violations of design invariants (spec §5.8–5.12): polling patterns (busy-wait or setInterval/time.sleep loops on node values), imperative triggers bypassing graph topology, bare Promises/queueMicrotask/setTimeout (TS) or asyncio.ensure_future/create_task/threading.Timer (PY) for reactive scheduling, direct Date.now()/performance.now() (TS) or time.time_ns()/time.monotonic_ns() (PY) usage (must use core/clock.ts or core/clock.py), hardcoded message type checks instead of messageTier/message_tier utilities, and Phase 4+ APIs that leak protocol internals (DIRTY/RESOLVED/bitmask) into their primary surface. **If the change touches `src/patterns/` or `src/compat/`, verify the implementation against COMPOSITION-GUIDE.md categories (§1 lazy activation, §2 subscription ordering, §3 null guards, §5 wiring order, §7 feedback cycles, §8 SENTINEL gate).** For each finding: **title** | **trigger_condition** | **potential_consequence** | **location** | **suggested_guard**.
 
 ### 1c. Triage findings
 
@@ -59,7 +61,7 @@ Group findings:
 1. **Needs Decision** — architecture-affecting or ambiguous fixes
 2. **Auto-applicable** — clear fixes that follow existing patterns
 
-**Cross-language decision log:** For **Needs Decision** items that are architectural or affect TS/Python parity, add them to **`docs/optimizations.md`** under "Active work items". If **`graphrefly-py`** is available alongside this repo, add the same entry to **`graphrefly-py/docs/optimizations.md`**. If not available, call out mirroring for the user. When resolved, archive to `archive/optimizations/resolved-decisions.jsonl` per `docs/docs-guidance.md` § "Optimization decision log".
+**Cross-language decision log:** For **Needs Decision** items that are architectural or affect TS/Python parity, add them to **`docs/optimizations.md`** under "Active work items" (this repo is the single source of truth for both TS and PY). When resolved, archive to `archive/optimizations/resolved-decisions.jsonl` per `docs/docs-guidance.md` § "Optimization decision log".
 
 **Wait for user decisions on group 1. Group 2 can be applied immediately if user approves the batch.**
 
@@ -73,12 +75,19 @@ Apply the approved fixes from Phase 1.
 
 ## Phase 3: Final Checks
 
-Run all of these and fix any failures (do NOT skip or ignore):
+Run all checks for the affected repo(s) and fix any failures (do NOT skip or ignore):
 
+**TypeScript:**
 1. `pnpm test` — all tests must pass
 2. `pnpm run lint:fix` — fix lint issues
 3. `pnpm run build` — check for DTS/build problems
 
+**Python (if PY code was changed):**
+1. `cd ~/src/graphrefly-py && uv run pytest`
+2. `cd ~/src/graphrefly-py && uv run ruff check --fix src/ tests/`
+3. `cd ~/src/graphrefly-py && uv run ruff format src/ tests/`
+4. `cd ~/src/graphrefly-py && uv run mypy src/`
+
 If a failure is related to an implementation design question, **HALT** and raise it to the user before fixing.
 
 ---
@@ -93,11 +102,11 @@ Update documentation when behavior or public API changed:
 
 - **`docs/docs-guidance.md`** — if documentation *conventions* or generator workflow change, update this file so `/qa` and contributors stay aligned
 - **`~/src/graphrefly/GRAPHREFLY-SPEC.md`** — only if the **spec** itself is intentionally revised (rare; use semver rules in spec §8)
-- **`docs/optimizations.md`** — add **new open decisions** under "Active work items"; when **resolved**, archive to `archive/optimizations/resolved-decisions.jsonl` per `docs/docs-guidance.md` § "Optimization decision log"; mirror to **`graphrefly-py`** if in workspace
+- **`docs/optimizations.md`** — add **new open decisions** under "Active work items". **Then actively sweep:** scan for any fully-resolved items (all sub-tasks DONE, no remaining TODOs) and archive them to `archive/optimizations/resolved-decisions.jsonl` per `docs/docs-guidance.md` § "Optimization decision log". Remove archived content from `optimizations.md` — it should contain only active/open items, anti-patterns, and deferred follow-ups.
 - **Structured JSDoc** on exported public APIs (Tier 1 — parameters, returns, examples per `docs-guidance`; source of truth for generated API pages)
 - **New public symbols** — barrel export + **`website/scripts/gen-api-docs.mjs` REGISTRY** entry, then `pnpm --filter @graphrefly/docs-site docs:gen` (or `docs:gen:check` in CI)
 - **`docs/test-guidance.md`** — if new test patterns are established
-- **`docs/roadmap.md`** — check off completed items; when a phase/group is fully done, archive to `archive/roadmap/*.jsonl` per `docs/docs-guidance.md` § "Roadmap archive"
+- **`docs/roadmap.md`** — check off completed items. **Then actively sweep:** scan for any fully-completed phase or item group and archive it to `archive/roadmap/*.jsonl` per `docs/docs-guidance.md` § "Roadmap archive". Remove archived content from `roadmap.md` — it should contain only active/open items.
 - **`CLAUDE.md`** — only if fundamental workflow/commands changed
 
 Do **not** hand-edit **`website/src/content/docs/api/*.md`** — regenerate from JSDoc via `docs:gen` per **`docs/docs-guidance.md`**.