--- /dev/null
+#+TITLE: skeleton_compare – Harmony skeleton comparison tool
+#+AUTHOR: Reasoning Technology
+
+* 1. Overview
+
+1.1
+~skeleton_compare~ compares a Harmony skeleton (=A=) with a derived or legacy project (=B=).
+
+1.2
+It answers:
+
+- How has B diverged from A?
+- What should be imported back into A?
+- What should be exported from A into B?
+- Which nodes are misplaced or suspicious?
+- Which nodes represent valid project-specific extensions?
+
+1.3
+The entrypoint in this project is the symlink:
+
+- =tool/skeleton_compaare=
+
+which points to:
+
+- =tool/skeleton_compare_source/CLI.py=
+
+* 2. Role in the Harmony ecosystem
+
+2.1
+Harmony defines a skeleton layout (directories, leaves, extension points).
+
+2.2
+Projects are expected to:
+
+- start from that skeleton
+- add work under approved extension points
+- keep core structure aligned over time
+
+2.3
+Reality diverges:
+
+- legacy projects that predate Harmony
+- projects with ad-hoc edits in skeleton areas
+- skeleton evolution over months or years
+
+2.4
+~skeleton_compare~ provides:
+
+- a structural comparison
+- a semantic comparison (types, topology)
+- a chronological comparison (mtimes)
+- actionable commands to re-align projects
+
+* 3. High-level behavior
+
+3.1
+Tree construction
+
+1. Build =tree_dict= for A (Harmony skeleton).
+2. Build =tree_dict= for B (other project).
+3. Attach metadata per relative path:
+
+ - =node_type= :: =directory= | =file= | =other= | =constrained=
+ - =dir_info= :: =root= | =branch= | =leaf= | =NA=
+ - =mtime= :: float seconds since epoch
+
+3.2
+Git ignore
+
+1. A simplified =.gitignore= model is applied.
+2. Some paths (e.g., =.git=) are always ignored.
+3. Only paths admitted by this model participate in comparisons.
+
+3.3
+Topology classification (relative to A)
+
+1. =in_between= :: under a directory in A, but not under any leaf in A.
+2. =below= :: under a leaf directory in A.
+3. Neither :: not under any directory known to A (ignored for most commands).
+
+3.4
+Chronological classification
+
+1. newer(B,A) :: B node has a newer mtime than A at the same path.
+2. older(B,A) :: B node has an older mtime than A at the same path.
+3. A-only :: path exists in A but not B.
+4. B-only :: path exists in B but not A.
+
+* 4. Command surface (conceptual)
+
+4.1
+~structure~
+
+1. Compares directory topology.
+2. Reports directories that:
+
+ - exist as directories in A
+ - are missing or non-directories in B
+
+3. Intended use:
+
+ - detect missing branches in projects
+ - detect structural drift
+
+4.2
+~import~
+
+1. Direction: B → A.
+2. Only considers:
+
+ - nodes in the =in_between= region of B
+ - that are new or absent in A
+
+3. Outputs:
+
+ - ~mkdir -p~ commands (when needed)
+ - ~cp --parents -a~ commands for files
+ - a comment list for nodes that cannot be handled automatically
+ (type mismatches, non-file/dir, constrained nodes)
+
+4. Intended use:
+
+ - mine “good ideas” in B that belong in the skeleton
+ - keep Harmony evolving based on real projects
+
+4.3
+~export~
+
+1. Direction: A → B.
+2. Considers:
+
+ - A-only nodes (present in A, missing in B)
+ - nodes where A’s file is newer than B’s file
+
+3. Outputs:
+
+ - ~mkdir -p~ commands for B
+ - ~cp --parents -a~ commands for files
+
+4. Intended use:
+
+ - bring B back into alignment with the current Harmony skeleton
+ - propagate skeleton fixes and improvements into projects
+
+4.4
+~suspicious~
+
+1. Reports nodes in B that are:
+
+ - inside A’s directory structure
+ - but not under any leaf directory
+
+2. Intended use:
+
+ - highlight questionable placements
+ - identify candidates for new skeleton structure
+ - catch misuse of the skeleton (work living in the “framework” layer)
+
+4.5
+~addendum~
+
+1. Reports nodes in B that are:
+
+ - under leaf directories in A
+
+2. Intended use:
+
+ - show work added at the intended extension points
+ - give a quick outline of “project-specific” content layered on Harmony
+
+4.6
+~all~
+
+1. Runs:
+
+ - =structure=
+ - =import=
+ - =export=
+ - =suspicious=
+ - =addendum=
+
+2. Intended use:
+
+ - periodic health check of a project against Harmony
+ - initial analysis when inheriting an old project
+
+* 5. Safety and behavior guarantees
+
+5.1
+No direct modification
+
+1. ~skeleton_compaare~ itself does not modify either tree.
+2. It only prints suggested shell commands.
+3. A human is expected to review and run those commands (or not).
+
+5.2
+Constrained and unknown nodes
+
+1. Some paths are “constrained”:
+
+ - object exists but metadata (e.g., ~mtime~) cannot be safely read
+ - typical for special files or broken links
+
+2. These are:
+
+ - classified as =constrained=
+ - never touched by import/export logic
+ - surfaced in “not handled automatically” lists
+
+5.3
+Robust to legacy layouts
+
+1. A and B are assumed to be non-overlapping roots.
+2. B does not have to be a clean Harmony derivative.
+3. The tool is designed to:
+
+ - tolerate missing branches
+ - tolerate ad-hoc additions
+ - still classify and report differences coherently
+
+* 6. How to run it
+
+6.1
+From inside the Harmony repo:
+
+#+begin_src sh
+cd /path/to/Harmony
+tool/skeleton_compaare help
+tool/skeleton_compaare usage
+tool/skeleton_compaare structure ../SomeProject
+tool/skeleton_compaare all ../Rabbit
+#+end_src
+
+6.2
+The CLI help (from ~doc.py~) is the canonical reference for:
+
+1. grammar and argument rules
+2. meaning of A and B
+3. exact semantics of each command
+
+This =.org= file is a conceptual overview for Harmony toolsmiths and administrators.
+
+* 7. Maintenance notes
+
+7.1
+Core modules
+
+1. =skeleton_compare_source/skeleton.py=
+ - tree construction
+ - topology classification
+ - “newer/older” logic
+ - in-between / below partitioning
+
+2. =skeleton_compare_source/command.py=
+ - high-level command semantics
+ - import/export planning and printing
+
+3. =skeleton_compare_source/CLI.py=
+ - argument classification
+ - environment checks
+ - dispatch to command handlers
+
+7.2
+Change discipline
+
+1. CLI behavior and text should be updated in:
+
+ - =doc.py= (help/usage text)
+ - this =.org= file (conceptual intent)
+
+2. Any behavioral change that affects:
+
+ - classification rules
+ - import/export semantics
+ - constrained handling
+
+ should be reflected here in section 3 or 4.
+
--- /dev/null
+#+TITLE: skeleton_compare – Harmony skeleton comparison tool
+#+AUTHOR: Reasoning Technology
+
+* 1. Overview
+
+1.1
+~skeleton_compare~ compares a Harmony skeleton (=A=) with a derived or legacy project (=B=).
+
+1.2
+It answers:
+
+- How has B diverged from A?
+- What should be imported back into A?
+- What should be exported from A into B?
+- Which nodes are misplaced or suspicious?
+- Which nodes represent valid project-specific extensions?
+
+1.3
+The entrypoint in this project is the symlink:
+
+- =tool/skeleton_compaare=
+
+which points to:
+
+- =tool/skeleton_compare_source/CLI.py=
+
+* 2. Role in the Harmony ecosystem
+
+2.1
+Harmony defines a skeleton layout (directories, leaves, extension points).
+
+2.2
+Projects are expected to:
+
+- start from that skeleton
+- add work under approved extension points
+- keep core structure aligned over time
+
+2.3
+Reality diverges:
+
+- legacy projects that predate Harmony
+- projects with ad-hoc edits in skeleton areas
+- skeleton evolution over months or years
+
+2.4
+~skeleton_compare~ provides:
+
+- a structural comparison
+- a semantic comparison (types, topology)
+- a chronological comparison (mtimes)
+- actionable commands to re-align projects
+
+* 3. High-level behavior
+
+3.1
+Tree construction
+
+1. Build =tree_dict= for A (Harmony skeleton).
+2. Build =tree_dict= for B (other project).
+3. Attach metadata per relative path:
+
+ - =node_type= :: =directory= | =file= | =other= | =constrained=
+ - =dir_info= :: =root= | =branch= | =leaf= | =NA=
+ - =mtime= :: float seconds since epoch
+
+3.2
+Git ignore
+
+1. A simplified =.gitignore= model is applied.
+2. Some paths (e.g., =.git=) are always ignored.
+3. Only paths admitted by this model participate in comparisons.
+
+3.3
+Topology classification (relative to A)
+
+1. =in_between= :: under a directory in A, but not under any leaf in A.
+2. =below= :: under a leaf directory in A.
+3. Neither :: not under any directory known to A (ignored for most commands).
+
+3.4
+Chronological classification
+
+1. newer(B,A) :: B node has a newer mtime than A at the same path.
+2. older(B,A) :: B node has an older mtime than A at the same path.
+3. A-only :: path exists in A but not B.
+4. B-only :: path exists in B but not A.
+
+* 4. Command surface (conceptual)
+
+4.1
+~structure~
+
+1. Compares directory topology.
+2. Reports directories that:
+
+ - exist as directories in A
+ - are missing or non-directories in B
+
+3. Intended use:
+
+ - detect missing branches in projects
+ - detect structural drift
+
+4.2
+~import~
+
+1. Direction: B → A.
+2. Only considers:
+
+ - nodes in the =in_between= region of B
+ - that are new or absent in A
+
+3. Outputs:
+
+ - ~mkdir -p~ commands (when needed)
+ - ~cp --parents -a~ commands for files
+ - a comment list for nodes that cannot be handled automatically
+ (type mismatches, non-file/dir, constrained nodes)
+
+4. Intended use:
+
+ - mine “good ideas” in B that belong in the skeleton
+ - keep Harmony evolving based on real projects
+
+4.3
+~export~
+
+1. Direction: A → B.
+2. Considers:
+
+ - A-only nodes (present in A, missing in B)
+ - nodes where A’s file is newer than B’s file
+
+3. Outputs:
+
+ - ~mkdir -p~ commands for B
+ - ~cp --parents -a~ commands for files
+
+4. Intended use:
+
+ - bring B back into alignment with the current Harmony skeleton
+ - propagate skeleton fixes and improvements into projects
+
+4.4
+~suspicious~
+
+1. Reports nodes in B that are:
+
+ - inside A’s directory structure
+ - but not under any leaf directory
+
+2. Intended use:
+
+ - highlight questionable placements
+ - identify candidates for new skeleton structure
+ - catch misuse of the skeleton (work living in the “framework” layer)
+
+4.5
+~addendum~
+
+1. Reports nodes in B that are:
+
+ - under leaf directories in A
+
+2. Intended use:
+
+ - show work added at the intended extension points
+ - give a quick outline of “project-specific” content layered on Harmony
+
+4.6
+~all~
+
+1. Runs:
+
+ - =structure=
+ - =import=
+ - =export=
+ - =suspicious=
+ - =addendum=
+
+2. Intended use:
+
+ - periodic health check of a project against Harmony
+ - initial analysis when inheriting an old project
+
+* 5. Safety and behavior guarantees
+
+5.1
+No direct modification
+
+1. ~skeleton_compaare~ itself does not modify either tree.
+2. It only prints suggested shell commands.
+3. A human is expected to review and run those commands (or not).
+
+5.2
+Constrained and unknown nodes
+
+1. Some paths are “constrained”:
+
+ - object exists but metadata (e.g., ~mtime~) cannot be safely read
+ - typical for special files or broken links
+
+2. These are:
+
+ - classified as =constrained=
+ - never touched by import/export logic
+ - surfaced in “not handled automatically” lists
+
+5.3
+Robust to legacy layouts
+
+1. A and B are assumed to be non-overlapping roots.
+2. B does not have to be a clean Harmony derivative.
+3. The tool is designed to:
+
+ - tolerate missing branches
+ - tolerate ad-hoc additions
+ - still classify and report differences coherently
+
+* 6. How to run it
+
+6.1
+From inside the Harmony repo:
+
+#+begin_src sh
+cd /path/to/Harmony
+tool/skeleton_compaare help
+tool/skeleton_compaare usage
+tool/skeleton_compaare structure ../SomeProject
+tool/skeleton_compaare all ../Rabbit
+#+end_src
+
+6.2
+The CLI help (from ~doc.py~) is the canonical reference for:
+
+1. grammar and argument rules
+2. meaning of A and B
+3. exact semantics of each command
+
+This =.org= file is a conceptual overview for Harmony toolsmiths and administrators.
+
+* 7. Maintenance notes
+
+7.1
+Core modules
+
+1. =skeleton_compare_source/skeleton.py=
+ - tree construction
+ - topology classification
+ - “newer/older” logic
+ - in-between / below partitioning
+
+2. =skeleton_compare_source/command.py=
+ - high-level command semantics
+ - import/export planning and printing
+
+3. =skeleton_compare_source/CLI.py=
+ - argument classification
+ - environment checks
+ - dispatch to command handlers
+
+7.2
+Change discipline
+
+1. CLI behavior and text should be updated in:
+
+ - =doc.py= (help/usage text)
+ - this =.org= file (conceptual intent)
+
+2. Any behavioral change that affects:
+
+ - classification rules
+ - import/export semantics
+ - constrained handling
+
+ should be reflected here in section 3 or 4.
+
projects / Harmony.git / commitdiff