From: Thomas Walker Lynch <eknp9n@reasoningtechnology.com>
Date: Wed, 19 Nov 2025 16:39:39 +0000 (+0000)
Subject: adds generated README to skeleton_compare_source
X-Git-Url: https://git.reasoningtechnology.com/?a=commitdiff_plain;h=a0188d7548e96476b5c7f0a758ab6b327aa05311;p=Harmony.git

adds generated README to skeleton_compare_source
---

diff --git a/tool/skeleton_compare_source/README.org b/tool/skeleton_compare_source/README.org
new file mode 100644
index 0000000..387780d
--- /dev/null
+++ b/tool/skeleton_compare_source/README.org
@@ -0,0 +1,278 @@
+#+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.
+
diff --git a/tool/skeleton_compare_source/Readme.org b/tool/skeleton_compare_source/Readme.org
new file mode 100644
index 0000000..387780d
--- /dev/null
+++ b/tool/skeleton_compare_source/Readme.org
@@ -0,0 +1,278 @@
+#+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.
+