feat: emit -> down

Author: clfhhc

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

@@ -22,9 +22,9 @@ Load context and plan the implementation in a single pass. **Parallelize all rea
 Read in parallel:
 
 - **`~/src/graphrefly/GRAPHREFLY-SPEC.md`** — primary behavioral authority; read sections relevant to the task
-- **`docs/optimizations.md`** — built-in optimizations, cross-language notes, and **open design decisions** (read when touching protocol, batch, node lifecycle, or parity with graphrefly-ts)
+- `docs/optimizations.md` — **active work items**, anti-patterns, and **deferred follow-ups** (read when touching protocol, batch, node lifecycle, or parity). Resolved decisions are archived in `archive/optimizations/*.jsonl` — search there for historical context (see `docs/docs-guidance.md` § "Optimization decision log")
 - **`docs/test-guidance.md`** — checklists for the layer you touch (protocol, node, graph, operators)
-- **`docs/roadmap.md`** — phase alignment and acceptance criteria (read for new features or scope questions)
+- **`docs/roadmap.md`** — phase alignment and acceptance criteria (active/open items only; completed phases archived to `archive/roadmap/*.jsonl`)
 - **`archive/docs/SESSION-graphrefly-spec-design.md`** — design lineage, simplifications vs callbag-recharge, scenario validation
 - Any files the user referenced in $ARGUMENTS
 - Relevant source under `src/graphrefly/{core,graph,extra}/`
@@ -73,7 +73,7 @@ Prioritize (in order):
 
 Do NOT treat backward compatibility as a primary constraint pre-1.0 unless the user says otherwise.
 
-**Cross-language decision log:** If Phase 1–2 surface an **architectural or product-level** question (protocol semantics, batch/node invariants, parity with TypeScript, or anything that needs a spec/product call), **jot it down** in **`docs/optimizations.md`** — use **Open design decisions** or **Cross-language implementation notes** as appropriate. If the sibling repo **`graphrefly-ts`** is available (e.g. `../graphrefly-ts` next to this checkout), add a **matching** entry to **`graphrefly-ts/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.
+**Cross-language decision log:** If Phase 1–2 surface an **architectural or product-level** question (protocol semantics, batch/node invariants, parity with TypeScript, or anything that needs a spec/product call), **jot it down** in **`docs/optimizations.md`** under **"Active work items"**. If the sibling repo **`graphrefly-ts`** is available, add a **matching** entry to **`graphrefly-ts/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".
 
 **Wait for user approval before proceeding.**
 
@@ -113,6 +113,6 @@ After user approves (full mode) or after Phase 1 (light mode, no escalation):
 
 4. Fix any failures
 
-If implementation leaves an **open architectural decision** (deferred behavior, parity caveat, or “needs spec” item), update **`docs/optimizations.md`** here and mirror to **`graphrefly-ts/docs/optimizations.md`** when that repo is available.
+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-ts/docs/optimizations.md`** when that repo is available. When resolved, archive to `archive/optimizations/resolved-decisions.jsonl` per `docs/docs-guidance.md`.
 
 When done, briefly list files changed and new exports. Suggest running **`/qa`** for adversarial review and final checks.

.claude/skills/parity/SKILL.md

@@ -18,8 +18,8 @@ Determine scope from $ARGUMENTS:
 - If `full`, scan all implemented phases in both roadmaps.
 
 Read in parallel:
-- **This repo:** `docs/optimizations.md` (cross-language notes + gaps), `docs/roadmap.md`, `~/src/graphrefly/GRAPHREFLY-SPEC.md` (relevant sections)
-- **Sibling repo:** `~/src/graphrefly-ts/docs/optimizations.md`, `~/src/graphrefly-ts/docs/roadmap.md`
+- **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-ts/docs/optimizations.md`, `~/src/graphrefly-ts/archive/optimizations/*.jsonl`, `~/src/graphrefly-ts/docs/roadmap.md` (active/open items only; completed phases archived to `archive/roadmap/*.jsonl`)
 - Source files in the scoped area from **both** repos
 - Test files in the scoped area from **both** repos
 
@@ -117,8 +117,8 @@ After user approves:
    - Code + tests in `~/src/graphrefly-ts/`
    - Run `cd ~/src/graphrefly-ts && pnpm test` — fix failures
 4. Update `docs/optimizations.md` in **both** repos:
-   - Remove resolved gaps from cross-language tables
-   - Add any new decisions to the appropriate section
+   - 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"
 
 ---
 

.claude/skills/qa/SKILL.md

@@ -59,7 +59,7 @@ Group:
 1. **Needs Decision** — architecture-affecting or ambiguous
 2. **Auto-applicable** — clear fixes matching existing patterns
 
-**Cross-language decision log:** For **Needs Decision** items that are architectural or affect Python/TypeScript parity, note them in **`docs/optimizations.md`** (e.g. **Open design decisions** or **Cross-language implementation notes**). If **`graphrefly-ts`** is available alongside this repo, add the same bullet to **`graphrefly-ts/docs/optimizations.md`**. If not available, call out mirroring for the user.
+**Cross-language decision log:** For **Needs Decision** items that are architectural or affect Python/TypeScript parity, add them to **`docs/optimizations.md`** under "Active work items". If **`graphrefly-ts`** is available alongside this repo, add the same entry to **`graphrefly-ts/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".
 
 **Wait for user decisions on group 1. Group 2 can be applied when the user approves the batch.**
 
@@ -94,8 +94,8 @@ Update documentation as appropriate:
 
 - **`docs/docs-guidance.md`** — if documentation *conventions* or generator commands change, update this file so `/qa` stays aligned
 - **`~/src/graphrefly/GRAPHREFLY-SPEC.md`** — only if the user-owned spec change is part of this task (usually avoid; spec is shared with graphrefly-ts)
-- **`docs/optimizations.md`** — when this review records **open architectural decisions** or cross-language parity notes; mirror substantive entries to **`graphrefly-ts/docs/optimizations.md`** if that repo is in the workspace
-- **`docs/roadmap.md`** — mark items done, add items if scope changed
+- **`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-ts`** if in workspace
+- **`docs/roadmap.md`** — mark items done; when a phase/group is fully done, archive to `archive/roadmap/*.jsonl` per `docs/docs-guidance.md` § "Roadmap archive"
 - **`docs/test-guidance.md`** — if new test patterns or file conventions were established
 - **`archive/docs/`** — session or design notes only when explicitly part of the task
 - **Structured docstrings** (Google-style: summary, Args, Returns, Examples) on exported public APIs — Tier 1 per **`docs/docs-guidance.md`**; keep semantics aligned with graphrefly-ts JSDoc where APIs match

TRASH-FILES.md

@@ -0,0 +1,2 @@
+emit_with_batch.md - moved to TRASH/ - renamed to down_with_batch; API page will be regenerated by docs:gen
+EmitStrategy.md - moved to TRASH/ - renamed to DownStrategy; API page will be regenerated by docs:gen