docs: TODO.restructure — eliminate JSON IR, .isc direct everywhere

10 TODOs for architecture restructure:
01 TS ISC parser (Peggy)
02 Website serve .isc instead of .json
03 Map pages from .isc at build time
04 TS ISC loader strategy
05 Remove JSON IR primary pipeline
06 Ruby JsonIR as optional export
07 Cross-runtime parity testing
08 CI validate .isc in all runtimes
09 Open PRs and merge
10 IS 1 specification

Core principle: .isc is single source format.
Both runtimes parse .isc directly. No compilation, no drift.

Author: ronaldtse

TODO.restructure/01-ts-isc-parser-peggy.md

@@ -0,0 +1,66 @@
+# 01 — TS ISC Parser (Peggy grammar)
+
+## Priority: P0 — blocks all website restructure work
+
+## Problem
+The TS runtime currently consumes compiled JSON IR (`.json` files generated
+by Ruby). To eliminate JSON IR, the TS runtime needs its own ISC parser.
+
+## Design
+
+Port the Ruby Parslet grammar to Peggy (PEG parser generator for JS/TS).
+The grammar rules map 1:1:
+
+| Parslet (Ruby) | Peggy (JS) |
+|----------------|------------|
+| `str("system")` | `"system"` |
+| `whitespace` | `\\s+` |
+| `quoted_string` | `'"' ('\\\\' ./ | !'"' .)* '"'` |
+| `braced(inner)` | `'{' \\s* inner \\s* '}'` |
+| `rule(:name) do ... end` | `name = ...` |
+
+### Structure
+```
+interscript-ts/
+  src/
+    isc/
+      grammar.peggy          # Peggy grammar (source of truth for TS)
+      parser.ts              # Wrapper: parse(src) → document hash
+      document-builder.ts    # Hash → typed CompiledMap
+      types.ts               # IscDocument, IscStage, IscRule, IscItem types
+  test/
+    isc/
+      parser.test.ts         # Unit tests
+      parity.test.ts         # Cross-validate with Ruby document hashes
+```
+
+### Grammar scope (from Ruby Parslet)
+- System block: `system "CODE" { body }`
+- Metadata: `metadata { key value ... }`
+- Tests: `tests { "input" -> "expected" }`
+- Aliases: `aliases { name = item }`
+- Stages: `stage name { parallel { ... } sub "a" "b" ... }`
+- Items: quoted strings, any(), capture(), ref(), none, primitives
+- Constraints: before, after, not_before, not_after
+- Directives: run, separate, compose, downcase/upcase/title_case
+
+### API
+```typescript
+import { parseIsc } from "interscript-ts/isc"
+
+const doc = parseIsc(iscSource, "map.isc")
+// doc: { systemCode, metadata, tests, stages, aliases, dependencies }
+```
+
+### Loader strategy
+```typescript
+import { iscStrategy } from "interscript-ts"
+
+configure({ strategies: [iscStrategy({ baseUrl: "/maps" })] })
+// Fetches /maps/foo.isc, parses, feeds to runtime
+```
+
+## Verification
+- Parse all 289 .isc files
+- Document hash matches Ruby document hash (cross-validate)
+- Transliteration output matches Ruby 100%

TODO.restructure/02-website-serve-isc.md

@@ -0,0 +1,29 @@
+# 02 — Website: serve .isc files instead of .json
+
+## Priority: P0
+
+## Problem
+The website serves compiled JSON IR from `/public/maps/*.json`.
+These are generated by Ruby from `.imp` files (now `.isc`).
+
+## Solution
+Replace JSON IR files with `.isc` source files. The TS ISC parser
+handles parsing at load time.
+
+### Changes
+1. Copy 289 `.isc` files from maps repo to `interscript.org/public/maps/`
+2. Remove 291 `.json` files from `interscript.org/public/maps/`
+3. Update `MapExplorer.vue` to use `iscStrategy` instead of `bundledStrategy`
+4. Update transliteration worker to use ISC loader
+
+### Performance consideration
+Parsing .isc in the browser is slower than loading pre-compiled JSON.
+Mitigation:
+- Web Worker parses off main thread
+- Cache parsed documents in IndexedDB
+- Pre-parse at build time for SSG pages (map detail)
+
+### Verification
+- All 38 E2E tests pass
+- Full-map validation (37 tests) passes
+- 7,502-sample parity test shows 0 diffs

TODO.restructure/03-map-pages-from-isc.md

@@ -0,0 +1,34 @@
+# 03 — Website: render map pages from .isc at build time
+
+## Priority: P1
+
+## Problem
+Map detail pages (e.g., `/maps/bgnpcgn-ukr-Cyrl-Latn-2019`) currently
+render from JSON IR metadata. They could render directly from .isc source.
+
+## Solution
+At Astro build time:
+1. Read each `.isc` file
+2. Parse with TS ISC parser (or Ruby if building with Ruby available)
+3. Extract metadata, tests, stage structure
+4. Render to static HTML
+
+### Pages affected
+- `/maps/[code]` — map detail (metadata, rules, tests)
+- `/maps` — catalogue (list all maps with metadata)
+- `/authorities/[auth]` — authority grouping
+
+### Implementation
+```typescript
+// astro.config or scripts/generate-map-pages.ts
+import { parseIsc } from "interscript-ts/isc"
+import { readFileSync } from "fs"
+
+const maps = readFileSync("public/maps/*.isc").map(parseIsc)
+// Generate static pages from parsed documents
+```
+
+### Benefit
+- No JSON IR files needed
+- Map pages always reflect the latest .isc source
+- No compilation step or drift

TODO.restructure/04-ts-isc-loader.md

@@ -0,0 +1,37 @@
+# 04 — TS runtime: ISC loader strategy
+
+## Priority: P1
+
+## Problem
+The TS runtime has load strategies for JSON IR (`bundledStrategy`,
+`httpStrategy`). Need a new strategy that loads `.isc` source files
+and parses them on the fly.
+
+## Design
+```typescript
+// src/isc/isc-loader.ts
+import { parseIsc } from "./parser"
+import { normaliseMap } from "../types"
+
+export function iscStrategy(opts: { baseUrl: string }): LoadStrategy {
+  return {
+    async load(code: string): Promise<CompiledMap | null> {
+      const res = await fetch(`${opts.baseUrl}/${code}.isc`)
+      if (!res.ok) return null
+      const source = await res.text()
+      const doc = parseIsc(source, code)
+      return normaliseMap(doc) // Convert to CompiledMap shape
+    }
+  }
+}
+```
+
+### Backward compatibility
+Keep existing JSON IR strategies as optional. Users who prefer
+pre-compiled JSON can still use `bundledStrategy` or `httpStrategy`.
+The new `iscStrategy` is the recommended default.
+
+## Verification
+- `transliterate("bgnpcgn-ukr-Cyrl-Latn-2019", "Антон")` works with iscStrategy
+- All 289 maps load and transliterate correctly
+- Performance: parse time < 100ms for 95% of maps (large CJK maps may be slower)

TODO.restructure/05-remove-jsonir-primary.md

@@ -0,0 +1,24 @@
+# 05 — Remove JSON IR as primary pipeline
+
+## Priority: P2 (after 01-04 are done)
+
+## Problem
+`Interscript::Compiler::JsonIR` generates JSON IR from Node::Document.
+This was the ONLY way to feed maps to the TS runtime. With a TS ISC
+parser, JSON IR is no longer needed as the primary pipeline.
+
+## Solution
+1. Keep JsonIR compiler as an OPTIONAL export (for backward compat)
+2. Remove it from the default build pipeline
+3. Remove JSON IR files from the website
+4. Remove the `gen-parity-fixtures.rb` dependency on JSON IR
+
+## What stays
+- `Interscript::Compiler::JsonIR` class — still available for users who
+  want pre-compiled maps
+- `interscript.org/public/maps/*.json` — removed (replaced by .isc)
+
+## Migration path for existing users
+1. Users who load `.json` via `bundledStrategy` → switch to `iscStrategy`
+2. Users who generate `.json` via Ruby → can still use JsonIR compiler
+3. The .isc files are the canonical source for both runtimes

TODO.restructure/06-ruby-jsonir-optional.md

@@ -0,0 +1,34 @@
+# 06 — Ruby: keep JsonIR as optional export
+
+## Priority: P2
+
+## Problem
+The JsonIR compiler should remain available but not be the default
+pipeline. Users who want pre-compiled JSON for performance can still
+generate it.
+
+## Design
+```ruby
+# Generate JSON IR from .isc (optional, not default)
+Interscript.load_path.unshift("maps")
+doc = Interscript.parse_isc("maps/foo.isc")  # Parse .isc
+node = Interscript::Isc::NodeAdapter.to_interscript_node(doc)
+json = Interscript::Compiler::JsonIR.compile(node)
+File.write("foo.json", json)
+```
+
+## No code change needed
+The existing `Interscript::Compiler::JsonIR` already works with
+Node::Document objects. The NodeAdapter converts .isc → Node.
+So the pipeline `.isc → parse → NodeAdapter → JsonIR` already works.
+
+## Verification
+```ruby
+# Generate IR from .isc and compare with old .json
+node = Isc::NodeAdapter.to_interscript_node(
+  Isc::DocumentBuilder.build(
+    Isc::Parser.parse(File.read("maps/foo.isc"))))
+ir = Interscript::Compiler::JsonIR.compile(node)
+old_ir = JSON.parse(File.read("public/maps/foo.json"))
+# ir and old_ir should be equivalent
+```

TODO.restructure/07-cross-runtime-parity.md

@@ -0,0 +1,53 @@
+# 07 — Cross-runtime parity testing
+
+## Priority: P1
+
+## Problem
+With two ISC parsers (Ruby Parslet + TS Peggy), we need to verify
+they produce semantically equivalent document models.
+
+## Design
+1. Ruby parses all 289 .isc files → document hashes
+2. TS parses all 289 .isc files → document hashes
+3. Compare: same system code, same test count, same stage structure
+4. Compare: same transliteration output for all test vectors
+
+### Test structure
+```
+interscript-ts/test/isc/
+  cross-parity.test.ts   # Compare TS parse vs Ruby parse
+  transliteration.test.ts # Compare TS transliteration vs known-good
+```
+
+### Ruby side: export reference hashes
+```bash
+ruby -Ilib -e '
+  require "interscript/isc"
+  require "json"
+  results = {}
+  Dir.glob("../maps/maps/*.isc").each do |path|
+    tree = Isc::Parser.parse(File.read(path))
+    doc = Isc::DocumentBuilder.build(tree)
+    results[doc[:systemCode]] = {
+      tests: doc[:tests].size,
+      stages: doc[:stages].size,
+    }
+  end
+  File.write("test/fixtures/reference-hashes.json", JSON.pretty_generate(results))
+'
+```
+
+### TS side: parse and compare
+```typescript
+describe("cross-runtime parity", () => {
+  const refs = JSON.parse(readFileSync("test/fixtures/reference-hashes.json"))
+  for (const code of Object.keys(refs)) {
+    it(`${code}: matches Ruby parse`, () => {
+      const src = readFileSync(`../maps/maps/${code}.isc`, "utf8")
+      const doc = parseIsc(src)
+      expect(doc.tests.length).toBe(refs[code].tests)
+      expect(doc.stages.length).toBe(refs[code].stages)
+    })
+  }
+})
+```

TODO.restructure/08-ci-validate-isc.md

@@ -0,0 +1,48 @@
+# 08 — CI: validate .isc parse in all runtimes
+
+## Priority: P2
+
+## Problem
+Need CI checks to verify .isc files parse correctly in both Ruby and TS.
+
+## Design
+### Ruby CI
+```yaml
+- name: ISC specs
+  run: rspec spec/interscript/isc/ --options /dev/null
+
+- name: Parse all maps
+  run: ruby -Ilib -e '
+    require "interscript/isc"
+    Dir.glob("../maps/maps/*.isc").each do |path|
+      Isc::Parser.parse(File.read(path), filename: File.basename(path))
+    end
+  '
+```
+
+### TS CI
+```yaml
+- name: ISC parser tests
+  run: npx vitest run test/isc/
+
+- name: Parse all maps
+  run: npx tsx -e '
+    import { parseIsc } from "./src/isc/parser"
+    import { readdirSync, readFileSync } from "fs"
+    for (const f of readdirSync("../maps/maps").filter(f => f.endsWith(".isc"))) {
+      parseIsc(readFileSync(`../maps/maps/${f}`, "utf8"))
+    }
+  '
+```
+
+### Maps repo CI
+```yaml
+- name: ISC parse check
+  run: |
+    cd ../interscript-ruby
+    ruby -Ilib -e 'require "interscript/isc"; Dir.glob("../maps/maps/*.isc").each { |p| Isc::Parser.parse(File.read(p), filename: File.basename(p)) }'
+
+- name: Codemod drift check (optional)
+  run: |
+    # Verify .isc files are valid (no manual edits broke the format)
+    # This is a lightweight check, not a full codemod re-run

TODO.restructure/09-open-prs.md

@@ -0,0 +1,24 @@
+# 09 — Open PRs and merge
+
+## Priority: P0 — blocks all other work
+
+## Steps
+
+### Maps repo PR
+```bash
+cd interscript/maps
+gh pr create --title "feat: replace .imp with .isc format (289 maps)" \
+  --body "All 289 maps converted from Ruby DSL to ISC format."
+```
+
+### Ruby repo PR
+```bash
+cd interscript/interscript-ruby
+gh pr create --title "feat: ISC format — parser, NodeAdapter, YAML round-trip, serializer" \
+  --body "Complete ISC infrastructure: 105 specs, 289/289 parse, NodeAdapter, YAML bridge, serializer."
+```
+
+### Merge order
+1. Maps repo PR first (provides .isc files)
+2. Ruby repo PR second (depends on .isc for locate)
+3. Website changes third (depends on both)

TODO.restructure/10-is1-specification.md

@@ -0,0 +1,20 @@
+# 10 — IS 1 specification (Metanorma)
+
+## Priority: P2
+
+## Goal
+Compile `spec/isc/document.adoc` and publish to the website.
+
+## Architecture impact
+The spec should document:
+- ISC as the canonical source format (not .imp or .json)
+- Both Ruby and TS parsers as first-class implementations
+- YAML round-trip as an optional interchange format
+- JsonIR as an optional compiled format
+
+## Steps
+1. Update spec/isc/document.adoc to reflect current grammar
+2. Add YAML round-trip annex
+3. Add TS parser specification
+4. Compile with Metanorma
+5. Publish to interscript.org/spec