fix(isc): deep equivalence verification + code quality + decompose/compose support

Deep equivalence harness:
- Add verify_isc_deep that compares rule counts, metadata, tests,
  aliases, and stages between .imp (Ruby DSL) and .isc (ISC parser)
- Reports 274/289 equivalent, 2 IMP-fail (ISC-only), 13 cosmetic differ

DocumentBuilder fixes:
- Properly extract notes values from Parslet tree (was returning raw hashes)
- Add normalize_heredoc to strip per-line indentation from description
  and generic field blocks, matching DSL YAML heredoc behavior
- Add filter_noop to remove phantom rules from empty parallel/sequence
  blocks that contain only comments
- Handle field_block in generic field extraction

Grammar fixes:
- compose_directive accepts both "compose" and legacy "decompose"
- remove_decompose keyword from codemod directive list

Code quality:
- Remove internal require calls from parser.rb, transform.rb,
  document_builder.rb — autoload chain in lib/interscript/isc.rb
  and grammar.rb handles lazy loading

Author: ronaldtse

exe/codemod-imp-to-isc

@@ -119,7 +119,7 @@ module Interscript
           elsif @scanner.scan(/stage\b/)
             @out << "stage"
             convert_stage_header
-          elsif @scanner.scan(/\b(parallel|sequence|separate|deep|compose|downcase|upcase|title_case)\b/)
+          elsif @scanner.scan(/\b(parallel|sequence|separate|deep|compose|decompose|downcase|upcase|title_case)\b/)
             @out << @scanner.matched
           elsif @scanner.scan(/\brababa\b/)
             # rababa config: "200" — special directive, pass through as comment
@@ -307,8 +307,9 @@ module Interscript
             @out << escape_braces(text)
             convert_indented_block_until_dedent(indent)
             @out << "\n#{indent}}"
-          elsif @scanner.scan(/(?:\A|\n)([ \t]+)([A-Za-z_][\w]*)[ \t]*:[ \t]*\n([ \t]+)(?![ \t]*(?:-|"|\[|\]|\|))(?![ \t]*$)/)
-            # Multi-line unquoted text value: `field:\n    text` (not list, quote, heredoc)
+          elsif @scanner.scan(/(?:\A|\n)([ \t]+)([A-Za-z_][\w]*)[ \t]*:[ \t]*\n([ \t]+)(?![ \t]*(?:-|"|\[|\]|\|))(?![ \t]*$)(?![ \t]*[A-Za-z_]\w*[ \t]*:)/)
+            # Multi-line unquoted text value: `field:\n    text` (not list, quote,
+            # heredoc, or another field declaration at the same indent)
             indent = @scanner[1]
             field = @scanner[2]
             @out << "\n#{indent}#{field} {"

lib/interscript/isc/document_builder.rb

@@ -1,8 +1,5 @@
 # frozen_string_literal: true
 
-require "interscript/isc/transform"
-require "interscript/isc/items"
-
 module Interscript
   module Isc
     # Builds an intermediate "document hash" from a raw parslet tree.
@@ -76,6 +73,10 @@ def unescape_braces(text)
         text.gsub(/\\([{}\\])/, '\1')
       end
 
+      def normalize_heredoc(text)
+        text.lines.map { |l| l.strip }.join("\n").strip + "\n"
+      end
+
       # Apply Transform to an identifier fragment.
       def ident(fragment)
         return "" if fragment.nil?
@@ -98,7 +99,10 @@ def extract_metadata(arr)
             h[:specification] << unquote(field[:specification])
           when field.key?(:notes)
             h[:notes] ||= []
-            Array(field[:notes]).each { |n| h[:notes] << unquote(n) }
+            Array(field[:notes]).each do |n|
+              note_val = n.is_a?(Hash) ? n[:note] : n
+              h[:notes] << unquote(note_val)
+            end
           when field.key?(:note)
             h[:notes] ||= []
             h[:notes] << unquote(field[:note])
@@ -108,12 +112,12 @@ def extract_metadata(arr)
           when field.key?(:relations)
             h[:relations] = extract_relations(field[:relations])
           when field.key?(:description)
-            h[:description] = unescape_braces(field[:description].to_s.strip)
+            h[:description] = normalize_heredoc(unescape_braces(field[:description].to_s))
           when field.key?(:field_name)
             # Generic field: identifier + raw value
             name = ident(field[:field_name]).to_sym
             if field.key?(:field_block)
-              h[name] = unescape_braces(field[:field_block].to_s.strip)
+              h[name] = normalize_heredoc(unescape_braces(field[:field_block].to_s))
             else
               raw = field[:field_value]
               val_str = case raw
@@ -177,8 +181,8 @@ def extract_stage(item)
       def extract_stage_items(n)
         return [] unless n.is_a?(Hash)
         case
-        when n[:sequence]  then [{ kind: :sequence,  rules: Array(n[:sequence]).map { |r| extract_rule(r) } }]
-        when n[:parallel]  then [{ kind: :parallel,  rules: Array(n[:parallel]).map { |r| extract_rule(r) } }]
+        when n[:sequence]  then [{ kind: :sequence,  rules: filter_noop(Array(n[:sequence]).map { |r| extract_rule(r) }) }]
+        when n[:parallel]  then [{ kind: :parallel,  rules: filter_noop(Array(n[:parallel]).map { |r| extract_rule(r) }) }]
         when n[:separate]  then [{ kind: :separate, separator: n[:separator] ? materialize(n[:separator]) : nil }]
         when n[:compose]   then [{ kind: :compose }]
         when n[:case]      then [{ kind: :string_case, op: n[:case].to_s }]
@@ -191,6 +195,16 @@ def extract_stage_items(n)
         end
       end
 
+      # Filter out noop rules (from: None, to: None) created by empty
+      # parallel/sequence blocks that contain only comments or whitespace.
+      def filter_noop(rules)
+        rules.reject do |r|
+          r.is_a?(Hash) &&
+            r[:from].is_a?(Items::None) &&
+            r[:to].is_a?(Items::None)
+        end
+      end
+
       def extract_rule(r)
         from_val = r.is_a?(Hash) ? r[:from] : nil
         to_val = r.is_a?(Hash) ? r[:to] : nil

lib/interscript/isc/grammar/concerns/stages.rb

@@ -60,7 +60,7 @@ module Stages
 
           # `compose` — compose decomposed characters (NFC-ish).
           rule(:compose_directive) do
-            str("compose").as(:compose)
+            (str("compose") | str("decompose")).as(:compose)
           end
 
           rule(:rule_line) do

lib/interscript/isc/parser.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "parslet"
-require "interscript/isc/grammar"
 
 module Interscript
   module Isc

lib/interscript/isc/transform.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "parslet"
-require "interscript/isc/items"
 
 module Interscript
   module Isc