+++ /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