docs: add TODO.complete/ with all remaining ISC migration work

00-isc-runtime-integration — bridge ISC document → Interscript::Node
01-commit-isc-to-maps-repo — push 289 .isc files
02-fix-deep-equivalence-diffs — 13 remaining cosmetic differences
03-fix-isc-specs — bundler/Ruby 3.4 workaround + spec syntax fixes
04-is1-specification — compile Metanorma spec document
05-performance-cjk-maps — Parslet backtracking on 40k+ line maps
06-ruby-dsl-array-keys-bug — STANDARD_ARRAY_KEYS silently drops fields

Author: ronaldtse

TODO.complete/00-isc-runtime-integration.md

@@ -0,0 +1,63 @@
+# 00 — ISC runtime integration: bridge ISC document → Interscript::Node
+
+## Priority: P0 (blocks .isc adoption)
+
+## Problem
+The ISC parser produces a document hash (`{metadata:, tests:, stages:, aliases:}`),
+but the existing `Interscript.transliterate()` only accepts:
+1. `.imp` files (parsed via Ruby DSL `instance_exec`)
+2. System codes resolved through `Interscript::Path`
+
+There is **no bridge** from ISC document hash to `Interscript::Node::Document`.
+Until this exists, `.isc` files cannot be used for actual transliteration.
+
+## Solution
+
+### 1. Create `Interscript::Isc::NodeAdapter`
+```
+lib/interscript/isc/node_adapter.rb
+```
+```ruby
+module Interscript::Isc
+  class NodeAdapter
+    def self.to_interscript_node(isc_doc)
+      Interscript::Node::Document.new.tap do |doc|
+        doc.metadata = build_metadata(isc_doc[:metadata])
+        doc.tests = build_tests(isc_doc[:tests])
+        isc_doc[:stages].each { |s| doc.stages[s[:name]] = build_stage(s) }
+        isc_doc[:aliases].each { |a| doc.aliases[a[:name]] = build_alias(a) }
+      end
+    end
+  end
+end
+```
+
+### 2. Update `Interscript::Path` to resolve `.isc` files
+```ruby
+# In Interscript::Path.find_map
+[".isc", ".imp"].each do |ext|
+  path = "#{dir}/#{name}#{ext}"
+  return path if File.exist?(path)
+end
+```
+
+### 3. Update `Interscript.load_map` to dispatch by extension
+```ruby
+def self.parse_map(path)
+  return Isc.load_file(path) if path.end_with?(".isc")
+  DSL.parse(File.basename(path, ".imp")) # legacy
+end
+```
+
+## Verification
+```ruby
+# Both should produce identical output:
+Interscript.transliterate("alalc-amh-Ethi-Latn-1997", "ሀለ")     # .imp
+Interscript.transliterate("alalc-amh-Ethi-Latn-1997", "ሀለ")     # .isc (if .isc exists)
+```
+
+## Autoload Registration
+Add to `lib/interscript/isc.rb`:
+```ruby
+autoload :NodeAdapter, "interscript/isc/node_adapter"
+```

TODO.complete/01-commit-isc-to-maps-repo.md

@@ -0,0 +1,41 @@
+# 01 — Commit .isc files to the maps repo
+
+## Priority: P0 (canonical source)
+
+## Problem
+All 289 `.isc` files are generated in `/tmp/isc-verify/` but not committed
+to the `interscript/maps` repo. The maps repo only has `.imp` files.
+
+## Solution
+
+### Steps
+1. Generate .isc files into the maps repo:
+```bash
+cd interscript-ruby
+ruby -Ilib exe/codemod-imp-to-isc --out-dir=../maps/maps ../maps/maps/*.imp
+```
+
+2. In the maps repo:
+```bash
+cd ../maps
+git checkout -b feat/isc-maps
+git add maps/*.isc
+git diff --cached --name-only | grep -c '.isc'  # should be 289
+git commit -m "feat: add ISC-format maps for all 289 systems"
+git push -u origin feat/isc-maps
+gh pr create --title "feat: add ISC maps (289 systems)" --body-file ...
+```
+
+### CI Guard
+Add a CI check that regenerates .isc from .imp and verifies no drift:
+```yaml
+# .github/workflows/isc-consistency.yml
+- name: Regenerate ISC
+  run: cd ../interscript-ruby && ruby -Ilib exe/codemod-imp-to-isc --out-dir=../maps/maps ../maps/maps/*.imp
+- name: Check for drift
+  run: cd ../maps && git diff --exit-code maps/*.isc
+```
+
+## Coordination
+- Ask user before pushing to `interscript/maps` (shared repo).
+- The maps repo has its own CI (CodeQL).

TODO.complete/02-fix-deep-equivalence-diffs.md

@@ -0,0 +1,43 @@
+# 02 — Fix remaining 13 deep equivalence differences
+
+## Priority: P1
+
+## Current State
+- 274/289 deep equivalent
+- 2 IMP-fail (bgnpcgn-tuk: Ruby DSL can't parse, ISC can)
+- 13 differ (cosmetic / edge cases)
+
+## Categories
+
+### A. Description whitespace (5 maps) — `normalize_heredoc`
+**Maps:** alalc-kor, gki-bel, var-pra, var-san + 1
+
+The `normalize_heredoc` method strips ALL leading whitespace per line. The
+Ruby DSL's YAML heredoc strips only the COMMON indent (dedent), preserving
+relative indentation.
+
+**Fix:** Replace the simple strip with a proper dedent algorithm:
+1. Find minimum indent across non-blank lines
+2. Strip that amount from every line
+3. Handle the first line specially (grammar consumed its leading whitespace
+   after the opening `{`)
+
+**Risk:** Changing normalize_heredoc regressed 91 maps last time (270→179).
+The new algorithm must be strictly better than the current simple strip.
+
+### B. Codemod edge cases (6 maps)
+**Maps:** alalc-tir x2, bgnpcgn-fas, mext-jpn, odni-ara/fas/prs
+
+Each has a unique metadata pattern the codemod mishandles:
+- `alalc-tir`: description followed by `implementation_notes: |` heredoc
+- `bgnpcgn-fas`: `TODO: Add tests` treated as metadata field
+- `mext-jpn`: CJK name field, description mismatch
+- `odni-*`: `notes: - item` or `[]` leaking into description
+
+**Fix:** Audit each .imp individually, extend codemod handlers.
+
+### C. Rule count (2 maps)
+- `din-san-Deva-Latn-33904-2018`: imp=155 isc=154 (off by 1, likely `run` or `deep`)
+- `var-ara-Arab-Arab-rababa`: imp=1 isc=0 (rababa directive → comment, expected)
+
+**Fix for din-san:** Diff the stage body item-by-item between .imp and .isc.

TODO.complete/03-fix-isc-specs.md

@@ -0,0 +1,65 @@
+# 03 — Fix ISC spec failures (bundler workaround)
+
+## Priority: P1
+
+## Current State
+- 73 ISC specs written, 50 pass, 23 fail
+- Failures are syntax issues, not logic errors:
+  - Metadata specs need system block wrapper
+  - Transform specs need real parser output
+
+## Remaining Failures
+
+### Metadata specs (10 failing)
+The grammar requires a root `system "..." { ... }` block. Metadata specs
+test `metadata { ... }` standalone, which fails.
+
+**Fix:** Wrap each metadata test:
+```ruby
+it "parses minimal metadata" do
+  tree = parser.parse(<<~ISC, filename: "t.isc")
+    system "TEST:eng-Latn:Latn:2026" {
+      metadata {
+        authority_id test
+      }
+      stage main { }
+    }
+  ISC
+  expect(tree[:system][:body]).to be_an(Array)
+end
+```
+
+### Transform specs (8 failing)
+Specs construct Parslet trees manually (`{ string: { simple: "x" } }`),
+but the actual parser output shape differs (e.g., `Parslet::Slice` instead
+of plain strings).
+
+**Fix:** Use real parser output:
+```ruby
+it "transforms a quoted string" do
+  src = %Q{system "X:e-Latn:Latn:1" { stage main { sub "x" "y" } }}
+  tree = parser.parse(src, filename: "t.isc")
+  doc = Interscript::Isc::DocumentBuilder.build(tree, filename: "t.isc")
+  rule = doc[:stages].first[:body].first
+  expect(rule[:from]).to be_a(Interscript::Isc::Items::StringValue)
+end
+```
+
+### Other (5 failing)
+- DocumentBuilder tests expecting `:tests` output shape
+- Codemod modifier kwargs test
+- Concatenation tests
+
+## Infrastructure Fix
+The project's `spec/spec_helper.rb` requires `bundler/setup` which fails on
+Ruby 3.4.8 (`DidYouMean::SPELL_CHECKERS` NameError).
+
+**Fix:** Update bundler or add a Ruby version guard. The ISC specs use their
+own `spec/interscript/isc/spec_helper.rb` that avoids bundler.
+
+## CI Integration
+Add to `.github/workflows/ci.yml`:
+```yaml
+- name: ISC specs
+  run: bundle exec rspec spec/interscript/isc/ --options /dev/null
+```

TODO.complete/04-is1-specification.md

@@ -0,0 +1,42 @@
+# 04 — IS 1 specification compilation and publication
+
+## Priority: P2
+
+## Current State
+- `spec/isc/document.adoc` exists but hasn't been compiled
+- The spec describes ISC format but may lag behind grammar changes
+- No published HTML/PDF
+
+## Steps
+
+### 1. Review spec against grammar
+- Verify all grammar rules documented
+- Add escaped-brace syntax (`\{`, `\}`) for raw text
+- Document `separate separator`, `decompose` directives
+- Add `any(space+line_end)` pattern
+
+### 2. Compile
+```bash
+bundle exec metanorma spec/isc/document.adoc
+```
+Produces HTML, PDF, and XML.
+
+### 3. Publish
+- Copy compiled HTML to `interscript.org/public/spec/`
+- Add a `/spec` page on the website linking to it
+- Version the spec (IS 1.0) and track changes
+
+## Spec Structure (reference: ISO 24229)
+1. Scope
+2. Normative references
+3. Terms and definitions
+4. System codes
+5. Metadata block
+6. Tests block
+7. Aliases block
+8. Stages (parallel, sequence, sub, run, separate, compose)
+9. Items (strings, primitives, constructors, functions)
+10. Constraints (before, after, not_before, not_after)
+11. Annex A: Migration from .imp (codemod)
+12. Annex B: Grammar reference (PEG)
+13. Annex C: Examples

TODO.complete/05-performance-cjk-maps.md

@@ -0,0 +1,51 @@
+# 05 — Performance: optimize Parslet parsing for large CJK maps
+
+## Priority: P2
+
+## Current State
+6 maps take 15-38s to parse:
+
+| Map | Lines | Time |
+|-----|-------|------|
+| var-kor-Kore-Hang-2013 | 30k | 38s |
+| lshk-yue-Hani-Latn-jyutping-1993 | 20k | 29s |
+| hk-yue-Hani-Latn-1888 | 20k | 23s |
+| acadsin-zho-Hani-Latn-2002 | 15k | 23s |
+| var-zho-Hani-Latn-wd-1979 | 43k | 20s |
+| sac-zho-Hans-Latn-1979 | 26k | 15s |
+
+## Root Cause
+Parslet PEG parser has O(n²) backtracking. The `alias_arg` rule's
+`zero_width_primitive.absent?` lookahead fires for every `any()` call.
+With 5000+ any() calls in var-zho, overhead compounds.
+
+## Optimization Options
+
+### A. Pre-compile .isc → .rb (eliminates runtime parsing entirely)
+Compile .isc to a .rb file that constructs Interscript::Node objects:
+```ruby
+# Generated from var-zho-Hani-Latn-wd-1979.isc
+doc = Interscript::Node::Document.new
+doc.stages[:main] = Interscript::Node::Stage.new
+doc.stages[:main].children << Interscript::Node::Group::Parallel.new(...)
+# ... 27,000+ rules
+```
+Load time: <1s (require vs 20s parse).
+
+### B. Switch parser engine
+- **Racc** (LALR): no backtracking, O(n)
+- **Tree-sitter**: C-speed, incremental parsing
+- **Hand-written recursive descent**: fastest, most maintenance
+
+### C. Memoize lookaheads
+Cache `keyword.absent?` and `zero_width_primitive.absent?` results per
+position. Requires Parslet monkey-patch or wrapper atom.
+
+## Recommendation
+**Option A** is the right long-term solution:
+1. .isc is the human-editable source format
+2. .rb (or .json IR) is the runtime-loaded artifact
+3. `rake compile` generates artifacts from sources
+4. No runtime parsing needed
+
+This aligns with the existing JsonIR compilation pipeline.

TODO.complete/06-ruby-dsl-array-keys-bug.md

@@ -0,0 +1,54 @@
+# 06 — Ruby DSL STANDARD_ARRAY_KEYS bug
+
+## Priority: P3 (ISC already correct)
+
+## Bug
+`lib/interscript/dsl/metadata.rb` line 47-61: methods for
+`notes`, `implementation_notes`, `original_notes`, `url` process input
+but **never store the result** in `@node`.
+
+```ruby
+STANDARD_ARRAY_KEYS.each do |sym|
+  define_method sym do |stuff|
+    stuff = Array(stuff)
+    stuff.map do |i|
+      case i
+      when String then i
+      else
+        warn "..."
+        i.inspect
+      end
+    end
+    # BUG: result is discarded. Missing: @node[sym] = result
+  end
+end
+```
+
+## Impact
+- Ruby DSL `metadata.data[:url]` returns nil for ALL maps
+- ISC parser correctly stores these fields
+- Deep equivalence checker must skip these fields
+
+## Fix
+```ruby
+STANDARD_ARRAY_KEYS.each do |sym|
+  define_method sym do |stuff|
+    @node[sym] = Array(stuff).map do |i|
+      case i
+      when String then i
+      else
+        warn "[#{@map_name}] Metadata key #{sym} expects String"
+        i.inspect
+      end
+    end
+  end
+end
+```
+
+## Verification
+After fix, remove the skip in `exe/verify_isc_deep`:
+```ruby
+skip_fields = [:nonstandard, :tests, :stages, :aliases, :dependencies]
+# Remove :url, :notes, :implementation_notes, :original_notes from skip
+```
+Re-run: all 289 maps should match on these fields.