From 3e864579c6fece64a52f7abe005f4935d955b18d Mon Sep 17 00:00:00 2001 From: Thomas Walker Lynch Date: Wed, 19 Nov 2025 16:40:22 +0000 Subject: [PATCH] . --- tool/skeleton_compare_source/Readme.org | 278 ------------------------ 1 file changed, 278 deletions(-) delete mode 100644 tool/skeleton_compare_source/Readme.org diff --git a/tool/skeleton_compare_source/Readme.org b/tool/skeleton_compare_source/Readme.org deleted file mode 100644 index 387780d..0000000 --- a/tool/skeleton_compare_source/Readme.org +++ /dev/null @@ -1,278 +0,0 @@ -#+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. - -- 2.20.1