+# Protect against accidental local .gitignore deletion
+**/scratchpad/*
+!**/scratchpad/.gitignore
+
+# so that .gitignore is not required in consumer/release
+/consumer/release
+
# Python
__pycache__/
*.py[cod]
.ipynb_checkpoints/
.pytest_cache/
-# editor backup files (optional)
+# C / compiled artifacts
+*.o
+*.a
+*.out
+*.so
+
+# OS and editor backup files
*~
*.bak
-
-# so that .gitignore is not required in user/release
-/user/release
+*.swp
+.DS_Store
+++ /dev/null
-Copyright © 2019, 2024, 2025, 2026 Reasoning Technology. All Rights Reserved.
-
-This software, including all source code, compiled code, text, images, graphics, and associated media (collectively, "the Software and Content"), is the proprietary property of Reasoning Technology.
-
-A limited license, revocable at any time, is granted to access and view the Software and Content strictly for normal web browsing purposes.
-
-Beyond this limited viewing permission, no other rights are granted. A person is strictly prohibited from copying, extracting, modifying, republishing, distributing, sublicensing, selling, or otherwise exploiting this Software and Content, in whole or in part, for any purpose, without express written consent from Reasoning Technology. No license to any underlying technology, patents, trademarks, or other intellectual property is granted or implied by this access.
--- /dev/null
+document/LICENSE
\ No newline at end of file
--- /dev/null
+window.RT_REPO_ROOT = "../../../";
+document.write('<script src="' + window.RT_REPO_ROOT + 'shared/style_directory_dict.js"></script>');
+document.write('<script src="' + window.RT_REPO_ROOT + 'shared/third_party/RT-style-JS_public/consumer/release/RT/core/loader.js"></script>');
+document.write('<script src="' + window.RT_REPO_ROOT + 'shared/third_party/RT-style-JS_public/consumer/release/RT/core/body_visibility_hidden.js"></script>');
+++ /dev/null
-<!DOCTYPE html>
-<html lang="en">
- <head>
- <meta charset="UTF-8">
- <title>Project Structure and Ontology</title>
- <script src="setup.js"></script>
- <script>
- window.StyleRT.include('RT/theme');
- window.StyleRT.include('RT/layout/article_tech_ref');
- </script>
- </head>
- <body>
- <RT-article>
- <RT-title
- author="Harmony Project Team"
- date="2026-03-06"
- title="Project Structure and Ontology">
- </RT-title>
-
- <RT-TOC level="1"></RT-TOC>
-
- <h1>Purpose</h1>
- <p>
- Harmony provides a language-agnostic project directory structure and maintenance tools for long-lived, multi-person team software development. The structure exists to enforce:
- </p>
- <ol>
- <li>Clarity about where things live.
- <ul>
- <li>Role-based work areas.</li>
- <li>Separation of skeleton, team member authored, machine-made, and third-party installed software.</li>
- </ul>
- </li>
- <li>A safe, predictable build and release workflow.</li>
- </ol>
-
- <h1>Setup</h1>
-
- <p>
- Python programmers speak of <RT-term>virtual environment</RT-term> and <RT-term>activate</RT-term>. In contrast, <RT-term>Harmony</RT-term> users speak of <RT-term>roles</RT-term> and <RT-term>setup</RT-term>. Whatever the terminology, this is about setting up the environment by giving values to environment variables. In Python there is one set of environment variable values independent of user role. With Harmony there is a different set of variables depending on the role the user is taking on.
- </p>
-
- <p>
- A person takes on a role by sourcing the top-level setup script and providing the target role. In a bash shell to take on the role of <RT-term>developer</RT-term> the command is, for example: <RT-code>. setup developer</RT-code>, or <RT-code>source setup developer</RT-code>. As of this writing, the supported roles are: <strong>administrator</strong>, <strong>consumer</strong>, <strong>developer</strong>, and <strong>tester</strong>.
- </p>
-
- <p>
- Behind the scenes, the <RT-code>setup</RT-code> script performs the following actions:
- </p>
-
- <ul>
- <li>Sources the project-wide setup (<RT-code>shared/authored/setup</RT-code>) to establish the core environment variables (e.g. <RT-code>REPO_HOME</RT-code> and <RT-code>PROJECT</RT-code>).</li>
- <li>Configures the <RT-code>PATH</RT-code> to include shared tools, library environments, and the specific <RT-code><role>/tool</RT-code> directory.</li>
- <li>Changes the working directory into the specified role's workspace.</li>
- <li>Sources the <RT-code><role>/tool/setup</RT-code> script. While the earlier steps apply the standard Harmony skeleton setup, this final step applies the role setup that is customized for this specific project.</li>
- </ul>
-
-
- <h1>Documentation</h1>
- <p>Documentation is placed closest to the role it pertains to.</p>
- <ul>
- <li><RT-code>consumer/release/document/</RT-code> : Documentation for end-users of released code (e.g., man pages, application manuals, library API references).</li>
- <li><RT-code>administrator/document/</RT-code> : Project-wide documentation covering structure, ontology, and workflow.</li>
- <li><RT-code>developer/document/</RT-code> : Documentation for developers, including coding standards and internal API guides.</li>
- <li><RT-code>tester/document/</RT-code> : Documentation for testers detailing test plans and tools.</li>
- <li><RT-code>shared/document/</RT-code> : Documentation on installing and configuring shared tools.</li>
- </ul>
-
- <h1>Authored, made, scratchpad, third_party, inherited, customizations</h1>
- <p>
- Files found in a directory named <RT-code>authored</RT-code> were written by project team members. They did not come with the Harmony skeleton, nor with the installation of other software. The project tools only read from <RT-code>authored</RT-code> directories. Typically these files constitute the intellectual property of a project.
- </p>
- <p>
- Files found in a directory named <RT-code>made</RT-code> were generated by tools in the project. Authors should not edit these files, nor create new files in such a directory, as the directory content is under control of the tools. If a made file requires editing, it is best to find the source of the file, and edit at that point.
- </p>
- <p>
- Files found in a directory named <RT-code>scratchpad</RT-code> are not tracked. Hence, a <RT-code>git clone</RT-code> will always return empty <RT-code>scratchpad</RT-code> directories. (Currently this is accomplished by putting a <RT-code>.gitignore</RT-code> file in every <RT-code>scratchpad</RT-code> directory.) It is common for tools to place intermediate files on a scratchpad. It is also common for files to be staged on a scratchpad. Tools play nice and use subdirectories on the pad, so a person can use a scratchpad as a temporary directory for files. There is a tool that comes with the Harmony skeleton with the same name, <RT-code>scratchpad</RT-code>, that is used to maintain scratchpads. Note that one of its commands is <RT-code>clear</RT-code> which deletes everything on a scratchpad.
- </p>
- <p>
- Third party software is installed under <RT-code>shared/third_party</RT-code>.
- </p>
- <p>
- Other files are said to be <RT-term>inherited</RT-term>, or to be <RT-term>customizations</RT-term>.
- </p>
- <p>
- If an authored file must be added to a project in a location other than an <RT-code>authored</RT-code> directory, it is best to create and edit the file in an <RT-code>authored</RT-code> directory, then to create a symbolic link that points back to it from that other location.
- </p>
- <p>
- This approach makes it clear where to find team work product, what is generated by the tools in the project, and what was 'installed' with the project.
- </p>
-
- <h1>Top-Level repository layout</h1>
- <p>
- A team member will source the project setup file to take on a role. As of this writing, the supported roles are: <RT-code>administrator</RT-code>, <RT-code>developer</RT-code>, <RT-code>tester</RT-code>, and <RT-code>consumer</RT-code>.
- </p>
-
- <ul>
- <li><RT-code>administrator/</RT-code> : Project-local tools and skeleton maintenance.</li>
- <li><RT-code>developer/</RT-code> : Primary workspace for developers.</li>
- <li><RT-code>tester/</RT-code> : Regression and validation workspace for testers.</li>
- <li><RT-code>consumer/</RT-code> : Consumption workspace holding the <RT-code>consumer/release</RT-code> directory.</li>
- <li><RT-code>shared/</RT-code> : Shared ecosystem tools and global environments.</li>
- </ul>
-
- <h2>The administrator work area</h2>
- <p>
- This directory holds the tools and documentation used to manage the project as a whole. It includes the HTML documentation for the project ontology and workflow, as well as project-local tools utilized by the administrator to maintain the Harmony skeleton.
- </p>
-
- <h2>The developer work area</h2>
- <p>
- This directory is entered by first going to the top-level directory of the project, then sourcing <RT-code>. setup developer</RT-code>.
- </p>
- <ul>
- <li><RT-code>authored/</RT-code> : Human-written source. Tracked by Git.</li>
- <li><RT-code>made/</RT-code> : Tracked artifacts generated by tools (e.g., links to CLI entry points).</li>
- <li><RT-code>experiment/</RT-code> : Try-it-here code. Short-lived spot testing.</li>
- <li><RT-code>scratchpad/</RT-code> : Git-ignored directory. Holds all intermediate build outputs, including the <RT-code>stage</RT-code> directory for releases.</li>
- <li><RT-code>tool/</RT-code> : Developer-specific tools (like the release and make scripts).</li>
- </ul>
-
- <h2>The tester work area</h2>
- <p>
- This directory is dedicated to formal testing, including regression suites. While a developer can run and keep informal spot tests in their <RT-code>experiment/</RT-code> directory, any experiment promoted to a formal test is moved here. This enforces the boundary between writing code and validating it.
- </p>
-
- <h2>The shared tree</h2>
- <p>
- This directory contains ecosystem tools and global environments available to all roles. This includes shared authored tools, as well as third-party installations (like Python virtual environments or compilers) required by the project.
- </p>
-
- <h2>The consumer tree</h2>
- <p>
- The <RT-code>consumer/release/</RT-code> tree is where developers put work product that is ready to be consumed. The entire <RT-code>consumer/release</RT-code> directory is git-ignored and treated as a transient deployment target.
- </p>
- <p>
- Artifacts arrive in the <RT-code>consumer/release/</RT-code> tree <em>only</em> when the developer invokes the release script, which performs a flat-copy from the developer's <RT-code>scratchpad/stage</RT-code> directory.
- </p>
-
- <h1>Releases</h1>
- <p>
- While the workflow document provides a deep dive, it is helpful to understand how directories relate to the concept of a release. There is a distinction between a developer release and a project release.
- </p>
- <ul>
- <li><strong>Developer Release:</strong> A developer releases when they determine a work product is ready for testing. They invoke a script to copy artifacts into the <RT-code>consumer/release/</RT-code> directory.</li>
- <li><strong>Project Release:</strong> A project is released when the tester and other team members determine the code in the <RT-code>consumer/release/</RT-code> directory is fully validated and ready for end users. This is enacted by creating a release branch on the version control system (e.g., GitHub), not by moving files to another directory.</li>
- </ul>
-
- <h1>Directory names</h1>
- <p>
- Each directory name is a <RT-term>property</RT-term> shared among the files contained within it. Hence, a full path forms a semantic sentence describing each file within it.
- </p>
- <p>
- Because a directory name represents a property, it is rarely plural. For example, when each and every file in a directory is a test, the directory is named <RT-code>test</RT-code>.
- </p>
- <p>
- When a property name <em>is</em> plural, it describes something about the internal nature of each file. For instance, a directory named <RT-code>constants</RT-code> implies that each individual file inside it (say, <RT-code>physics.py</RT-code>, <RT-code>math.py</RT-code>, and <RT-code>cosmology.py</RT-code>) provides a collection of multiple constants.
- </p>
- <p>
- The following list presents each property type in order of preference that we use when naming directories.
- </p>
- <ul>
- <li><strong>Role Association</strong> (<RT-code>administrator</RT-code>, <RT-code>developer</RT-code>, <RT-code>tester</RT-code>, <RT-code>consumer</RT-code>): Identifies the persona, whether human or AI, intended to interact with the files.</li>
- <li><strong>Provenance</strong> (<RT-code>authored</RT-code>, <RT-code>made</RT-code>): Indicates whether the file was created by an intellect or mechanically produced by a tool.</li>
- <li><strong>Capability</strong> (<RT-code>tool</RT-code>, <RT-code>document</RT-code>, <RT-code>experiment</RT-code>): Describes the primary function or structural nature of the file.</li>
- <li><strong>Lifecycle State</strong> (<RT-code>scratchpad</RT-code>, <RT-code>release</RT-code>): Denotes the persistence, volatility, or promotion status of the file.</li>
- <li><strong>Tracking Status</strong> (<RT-code>tracked</RT-code>, <RT-code>untracked</RT-code>): Specifies the version control expectations for the artifacts.</li>
- </ul>
-
- <p>
- In the Unix file system, a person must choose a single string to use as the directory name. Hence, we typically choose a primary property, though when needed, we use multiple property names separated by an underscore.
- </p>
-
- <h1>The version 2.2 Harmony directory tree</h1>
- <RT-code>
- 2026-03-07 10:38:58 Z [Harmony:administrator] Thomas_developer@StanleyPark
- §/home/Thomas/subu_data/developer/project§
- > tree Harmony
- Harmony
- ├── 0pus_Harmony
- ├── administrator
- │ ├── document
- │ │ ├── 00_Project_Structure.html
- │ │ ├── 01_Workflow_Build_Contract.html
- │ │ ├── Harmony.md
- │ │ └── setup.js
- │ └── tool
- │ ├── after_pull
- │ ├── archive
- │ ├── release
- │ └── setup
- ├── consumer
- │ ├── scratchpad
- │ └── tool
- │ └── env
- ├── developer
- │ ├── authored
- │ │ └── hello.cli.c
- │ ├── document
- │ │ ├── 02_RT_Code_Format.html
- │ │ ├── 03_Naming_and_Directory_Conventions.html
- │ │ ├── 04_Language_Addenda.html
- │ │ ├── ontology.org
- │ │ └── setup.js
- │ ├── experiment
- │ ├── made
- │ ├── scratchpad
- │ └── tool
- │ ├── do_all
- │ ├── make
- │ ├── makefile
- │ ├── release
- │ └── setup
- ├── LICENSE
- ├── scratchpad
- │ └── Harmony__79f9d52__2026-03-07_085628Z.tar
- ├── setup
- ├── shared
- │ ├── authored
- │ │ ├── scratchpad
- │ │ ├── setup
- │ │ ├── style
- │ │ └── version
- │ ├── document
- │ │ ├── install_generic.org
- │ │ ├── install_Python.org
- │ │ └── setup.js
- │ ├── made
- │ ├── style_directory_dict.js
- │ └── third_party
- │ ├── RT-style-JS_public -> ../../../RT-style-JS_public/
- │ └── upstream
- └── tester
- ├── authored
- │ └── test_routine.sh
- ├── RT_Format
- │ ├── RT_Format
- │ ├── RT_Format.el
- │ ├── test_0_data.c
- │ └── test_1_data.py
- └── tool
- └── setup
- </RT-code>
-
- </RT-article>
- </body>
-</html>
--- /dev/null
+<!DOCTYPE html>
+<html lang="en">
+ <head>
+ <meta charset="UTF-8">
+ <title>Introduction to Harmony</title>
+ <script src="setup.js"></script>
+ <script>
+ window.StyleRT.include('RT/theme');
+ window.StyleRT.include('RT/layout/article_tech_ref');
+ </script>
+ </head>
+ <body>
+ <RT-article>
+ <RT-title
+ author="Thomas Walker Lynch"
+ date="2026-03-07"
+ title="Introduction to Harmony">
+ </RT-title>
+
+ <RT-TOC level="1"></RT-TOC>
+
+ <h1>Purpose</h1>
+ <p>
+ Harmony provides a language-agnostic project directory structure and maintenance tools for long-lived, multi-person team software development. The structure exists to enforce:
+ </p>
+ <ol>
+ <li>Clarity about where things live.
+ <ul>
+ <li>Role-based work areas.</li>
+ <li>Separation of skeleton, team member authored, machine-made, and third-party installed software.</li>
+ </ul>
+ </li>
+ <li>A safe, predictable build and release workflow.</li>
+ </ol>
+
+ <p>
+ Harmony is a project skeleton, a set of tools and directories that have been checked into a git repository. To create a Harmony-based project, the project administrator performs these steps:
+ </p>
+ <ol>
+ <li>Clone the Harmony project to a local directory.</li>
+ <li>Remove the <RT-code>.git</RT-code> tree.</li>
+ <li>Rename the Harmony directory to the name of the new project.</li>
+ <li>Rename the <RT-code>0pus_Harmony</RT-code> file to reflect the name of the new project.</li>
+ <li>Add a line to the <RT-code>shared/tool/version</RT-code> file for the new project.</li>
+ <li><RT-code>git init -b core_developer_branch</RT-code></li>
+ </ol>
+
+ <p>
+ The order is important so as to protect the Harmony skeleton project from accidental check-ins from users.
+ </p>
+ <p>
+ Leave the Harmony skeleton version in the version file, so that project administrators can understand what has changed in the skeleton over time.
+ </p>
+ <p>
+ The <RT-code>core_developer_branch</RT-code> is the branch that the core development team works on. Releases are moved to release branches.
+ </p>
+
+ <h1>Setup</h1>
+
+ <p>
+ Harmony is language agnostic. When a project makes use of project-specific C, Python, NodeJS, Java, or other tools, the project administrator installs those tools into the <RT-code>shared/third_party</RT-code> directory. The project administrator then modifies the setup files so that paths point to the correct locations and environment variables have the proper values.
+ </p>
+ <p>
+ If a person clones the project and does not set up third-party tools, commands will fall through the search path and perhaps find system-installed tools. Using system default tools is generally undesirable because each person who clones the project might be running different versions. This variation makes it harder for team members to coordinate and for consumers of the project work product to build functioning tools.
+ </p>
+ <p>
+ Because multiple team members and consumers of the work product will have to repeat the third-party install process after cloning a project, the administrator should carefully document the installation steps and place the resulting documents in the <RT-code>shared/document</RT-code> directory. (The most common installation method is to clone the third party tool next to the project, then to symbolic link it under <RT-code>shared/third_party/</RT-code>.)
+ </p>
+ <p>
+ Python programmers who use virtual environments will be familiar with an analogous process. The term 'virtual environment' does not invoke any hardware virtualization features; rather, it is a local environment setup. To avoid confusion, a Harmony user refers instead to the 'project setup'. The command to establish the environment is called 'setup' instead of 'activate'. Also note that in Harmony, unlike in Python, there are multiple setups available, each tailored to the specific role a person takes on.
+ </p>
+ <p>
+ As of the time of this writing, the defined roles are: <strong>administrator</strong>, <strong>consumer</strong>, <strong>developer</strong>, and <strong>tester</strong>. A person takes on a role by sourcing the top-level <RT-code>setup</RT-code> script and giving the target role as an argument. For example, in a bash shell with <RT-code>></RT-code> as the prompt, the command is:
+ </p>
+
+ <RT-code>
+ > . setup <role>
+ </RT-code>
+
+ <p>
+ Specifically for the developer role:
+ </p>
+
+ <RT-code>
+ > . setup developer
+ </RT-code>
+
+ <p>
+ For the administrator role:
+ </p>
+
+ <RT-code>
+ > . setup administrator
+ </RT-code>
+
+ <p>
+ Instead of starting with a period, the <RT-code>source</RT-code> command can be spelled out explicitly, for example:
+ </p>
+
+ <RT-code>
+ > source setup tester
+ </RT-code>
+
+ <p>
+ Behind the scenes, the <RT-code>setup</RT-code> script performs the following actions:
+ </p>
+
+ <ul>
+ <li>Sources the project-wide setup (<RT-code>shared/tool/setup</RT-code>) to establish the core environment variables (e.g., <RT-code>REPO_HOME</RT-code> and <RT-code>PROJECT</RT-code>).</li>
+ <li>Conditionally sources <RT-code>shared/authored/setup</RT-code> (if present) to apply administrator-injected, project-specific tool configurations.</li>
+ <li>Configures the <RT-code>PATH</RT-code> to include shared tools, library environments, and the specific <RT-code><role>/tool</RT-code> directory.</li>
+ <li>Changes the working directory into the specified role's workspace.</li>
+ <li>Sources the <RT-code><role>/tool/setup</RT-code> script. While the earlier steps apply the standard Harmony skeleton setup, this final step applies the role setup that is customized for this specific project.</li>
+ </ul>
+
+ <h1>Directory name</h1>
+ <p>
+ A directory name is considered to be a <RT-term>property</RT-term> given to each file contained in the directory. A full path then forms a semantic sentence describing each file.
+ </p>
+ <p>
+ Because a directory name represents a property, it is rarely plural. For example, when each and every file in a directory is a test, the directory is named <RT-code>test</RT-code>.
+ </p>
+ <p>
+ We run into limitations when using a conventional file system as though it were a property based file system. One limitation is that we are forced to choose a single directory name for each file. When a set of files in a directory all share the same multiple properties, we can use a compound directory name with the properties separated by an underscore, but it is impractical to specify overlapping directory groupings, i.e. we can't arbitrarily define any number of properties for a file in this manner. We will see later how this affects Harmony when discussing <RT-term>authored</RT-term> files.
+ </p>
+ <p>
+ The following list presents each property type in order of preference when naming directories.
+ </p>
+ <ul>
+ <li><strong>Role Association</strong> (<RT-code>administrator</RT-code>, <RT-code>developer</RT-code>, <RT-code>tester</RT-code>, <RT-code>consumer</RT-code>): Identifies the persona, whether human or AI, intended to interact with the files.</li>
+ <li><strong>Provenance</strong> (<RT-code>authored</RT-code>, <RT-code>made</RT-code>): Indicates whether the file was created by an intellect or mechanically produced by a tool.</li>
+ <li><strong>Capability</strong> (<RT-code>tool</RT-code>, <RT-code>document</RT-code>, <RT-code>experiment</RT-code>): Describes the primary function or structural nature of the file.</li>
+ <li><strong>Lifecycle State</strong> (<RT-code>scratchpad</RT-code>, <RT-code>release</RT-code>): Denotes the persistence, volatility, or promotion status of the file.</li>
+ <li><strong>Tracking Status</strong> (<RT-code>tracked</RT-code>, <RT-code>untracked</RT-code>): Specifies the version control expectations for the artifacts.</li>
+ </ul>
+
+ <h1>Document directories</h1>
+ <p>
+ There is a directory for documents that talks about the project as a whole, one for each role, one for tools that are shared among the roles, and the released work product probably comes with a document directory of its own.
+ </p>
+ <ul>
+ <li><RT-code>document/</RT-code> : Top-level onboarding, project-wide structure, such as this document.</li>
+ <li><RT-code>consumer/release/document/</RT-code> : Documentation for end-users of released code (e.g., man pages, application manuals, library API references).</li>
+ <li><RT-code>administrator/document/</RT-code> : Documentation for maintaining the project skeleton and global tools.</li>
+ <li><RT-code>developer/document/</RT-code> : Documentation for developers, including coding standards and internal API guides.</li>
+ <li><RT-code>tester/document/</RT-code> : Documentation for testers detailing test plans and tools.</li>
+ <li><RT-code>shared/document/</RT-code> : Documentation on installing and configuring shared tools.</li>
+ </ul>
+
+ <p>
+ Note that the <RT-code>consumer/release</RT-code> directory is maintained by a tool. Said tool is unimaginatively also named <RT-code>release</RT-code> and is found in the developer's tool directory. Hence, documents that are part of a release probably originate from somewhere in the <RT-code>developer/authored</RT-code> directory, perhaps <RT-code>developer/authored/document</RT-code>.
+ </p>
+
+ <p>
+ Our developers write documents directly in HTML using the RT semantic tags. See the <RT-code>RT-style-JS_public</RT-code> project and the documentation there. A common approach is to copy another document and the <RT-code>setup.js</RT-code> file, then to type over the top of that other document. Only one <RT-code>setup.js</RT-code> file is used per directory. Be sure to edit the relative root path found at the top of <RT-code>setup.js</RT-code>. Plain text, emacs org, and mark down have all been used in prior versions of Harmony.
+ </p>
+
+
+ <h1>Authored, made, scratchpad, third_party, inherited, customizations</h1>
+
+ <p>
+ Files found in a directory named <RT-code>authored</RT-code> were written by project team members. They did not come with the Harmony skeleton, nor with the installation of other software. Project build tools treat <RT-code>authored</RT-code> directories as strictly read-only. Typically these files constitute the intellectual property of a project.
+ </p>
+
+ <p>
+ All source code that gets built into a release must be placed in the developers' <RT-code>authored</RT-code> directory. The story is not as clean for build tools and other files. New documents go into document directories, and new tools go into the tool directories, etc. As a specific example, the developer will almost certainly edit the <RT-code>developer/tool/make</RT-code> file.
+ </p>
+
+ <p>
+ When the Harmony version line in the <RT-code>shared/tool/version</RT-code> file is left in place, it is straightforward for a project administrator to determine which Harmony skeleton files have been edited in a project, and which new files have been added.
+ </p>
+
+ <p>
+ [As a historical note, in the first version of Harmony a directory or file was marked as <RT-term>authored</RT-term> by adding a pencil suffix, '🖉'. Tools then respected this, for example by refusing to delete such files. However, this ad hoc approach to properties was awkward, and people had difficulty typing the marker. When the pencils were dropped, a number of authored files, such as an edited <RT-code>developer/tool/make🖉</RT-code> file, were no longer explicitly marked as authored.]
+ </p>
+
+ <p>
+ Files found in a directory named <RT-code>scratchpad</RT-code> are not tracked. Hence, a <RT-code>git clone</RT-code> will always return empty <RT-code>scratchpad</RT-code> directories. It is common for tools to place intermediate files on a scratchpad. It is also common for files to be staged on a scratchpad. Tools play nice and use subdirectories on the pad, so a person who is aware of those subdirectory names can use a scratchpad as a temporary directory. There is a scratchpad maintenance tool that comes with the Harmony, called unimaginatively, <RT-code>scratchpad</RT-code>. Pay attention as one of its commands is <RT-code>clear</RT-code>, and that deletes everything on the current directory's scratchpad.
+ </p>
+
+ <p>
+ Third party software is installed under <RT-code>shared/third_party</RT-code>.
+ </p>
+
+ <p>
+ Other files are said to be <RT-term>inherited</RT-term>, or to be <RT-term>customizations</RT-term>.
+ </p>
+
+ <h1>Top-Level repository layout</h1>
+ <p>
+ A team member will source the project setup file to take on a role. As of this writing, the supported roles are: <RT-code>administrator</RT-code>, <RT-code>developer</RT-code>, <RT-code>tester</RT-code>, and <RT-code>consumer</RT-code>.
+ </p>
+
+ <ul>
+ <li><RT-code>administrator/</RT-code> : Project-local tools and skeleton maintenance.</li>
+ <li><RT-code>developer/</RT-code> : Primary workspace for developers.</li>
+ <li><RT-code>tester/</RT-code> : Regression and validation workspace for testers.</li>
+ <li><RT-code>consumer/</RT-code> : Consumption workspace holding the <RT-code>consumer/release</RT-code> directory.</li>
+ <li><RT-code>shared/</RT-code> : Shared ecosystem tools and global environments.</li>
+ </ul>
+
+ <h2>The administrator work area</h2>
+ <p>
+ This directory holds the tools and documentation used to manage the project as a whole. It includes the HTML documentation for the project ontology and workflow, as well as project-local tools utilized by the administrator to maintain the Harmony skeleton.
+ </p>
+
+ <h2>The developer work area</h2>
+ <p>
+ This directory is entered by first going to the top-level directory of the project, then sourcing <RT-code>. setup developer</RT-code>.
+ </p>
+ <ul>
+ <li><RT-code>authored/</RT-code> : Human-written source. Tracked by Git.</li>
+ <li><RT-code>made/</RT-code> : Tracked artifacts generated by tools (e.g., links to CLI entry points).</li>
+ <li><RT-code>experiment/</RT-code> : Try-it-here code. Short-lived spot testing.</li>
+ <li><RT-code>scratchpad/</RT-code> : Git-ignored directory. Holds all intermediate build outputs, including the <RT-code>stage</RT-code> directory for releases.</li>
+ <li><RT-code>tool/</RT-code> : Developer-specific tools (like the release and make scripts).</li>
+ </ul>
+
+ <h2>The tester work area</h2>
+ <p>
+ This directory is dedicated to formal testing, including regression suites. While a developer can run and keep informal spot tests in their <RT-code>experiment/</RT-code> directory, any experiment promoted to a formal test is moved here. This enforces the boundary between writing code and validating it.
+ </p>
+
+ <h2>The shared tree</h2>
+ <p>
+ This directory contains ecosystem tools and global environments available to all roles. This includes the shared tool directory, as well as third-party installations (like Python virtual environments or compilers) required by the project. To assist in project specific modifications to the Harmony skeleton, Harmony comes with an empty <RT-code>shared/authored</RT-code> directory that is listed earlier in the executable search path than <RT-code>shared/tool</RT-code>.
+ </p>
+
+ <h2>The consumer tree</h2>
+ <p>
+ The <RT-code>consumer/release/</RT-code> tree is where developers put work product that is ready to be consumed. The entire <RT-code>consumer/release</RT-code> directory is git-ignored and treated as a transient deployment target.
+ </p>
+ <p>
+ Artifacts arrive in the <RT-code>consumer/release/</RT-code> tree <em>only</em> when the developer invokes the release script, which performs a flat-copy from the developer's <RT-code>scratchpad/stage</RT-code> directory.
+ </p>
+
+ <h1>Releases</h1>
+
+ <p>
+ As a first step, a developer creates a <RT-term>release candidate</RT-term> inside of the <RT-code>consumer/release/</RT-code>. This is typically done by running <RT-code>make</RT-code> to stage the release, where it can be experimented on, followed by running <RT-code>release write</RT-code>. The developer will often modify the versions of one or both of those tools that come with the Harmony skeleton.
+ The release candidate remains stable until the next <RT-term>developer release</RT-term>.
+ </p>
+ <p>
+ Then the tester runs tests on the release candidate. Tests must only read from the <RT-code>consumer/release/</RT-code> directory, though local copies can be made and edited as experiments. Currently bugs are filed using an external issues tool.
+ </p>
+ <p>
+ It is common for a developer to open a second window on his desktop, and then enter the project as a tester in that second window. The developer can then make a release candidate, run the tests, edit source code, and perhaps tests, and then quickly spin through the test-debug-fix-release cycle repeatedly.
+ </p>
+ <p>
+ When the product manager determines the work product to be sufficiently reliable and feature rich, the administrator will make a <RT-term>project release</RT-term>. He will do this by creating a branch called <RT-code>release_v<major></RT-code> and tagging it. The major release numbers go up incrementally.
+ </p>
+
+ <h1> Modifying the setup </h1>
+
+ <p>
+ For project wide setup modifications create or edit <RT-code>shared/authored/setup</RT-code>. Note that the <RT-code>shared/authored/setup</RT-code> file is sourced after the inherited <RT-code>shared/tool/setup</RT-code> file, and before the <RT-code><role>/tool/setup</RT-code> file.
+ </p>
+
+ <p>
+ For role specific setup modifications edit the appropriate <RT-code><role>/tool/setup</RT-code> file.
+ </p>
+ <p>
+ If these approaches are not sufficient, then edit the setup scripts directly. Note however, that such changes
+ will appear when the Harmony sync tool is run.
+ </p>
+
+ <h1>The version 2.2 Harmony directory tree</h1>
+
+ <RT-code>
+ 2026-03-07 14:50:50 Z [Harmony:administrator] Thomas_PM@ManhattanSquare
+ §/home/Thomas/subu_data/PM/project§
+ > tree Harmony
+ Harmony
+ ├── 0pus_Harmony
+ ├── administrator
+ │ ├── authored
+ │ ├── document
+ │ │ ├── 00_Project_Structure.html
+ </RT-code>
+ <RT-code>
+ │ │ ├── 01_Workflow_Build_Contract.html
+ │ │ ├── Harmony.md
+ │ │ └── setup.js
+ │ └── tool
+ │ ├── after_pull
+ │ ├── archive
+ │ ├── release
+ │ └── setup
+ ├── consumer
+ </RT-code>
+ <RT-code>
+ │ ├── scratchpad
+ │ └── tool
+ │ └── env
+ ├── developer
+ │ ├── authored
+ │ │ └── hello.cli.c
+ │ ├── document
+ │ │ ├── 02_RT_Code_Format.html
+ │ │ ├── 03_Naming_and_Directory_Conventions.html
+ </RT-code>
+ <RT-code>
+ │ │ ├── 04_Language_Addenda.html
+ │ │ ├── ontology.org
+ │ │ └── setup.js
+ │ ├── experiment
+ │ ├── made
+ │ ├── scratchpad
+ │ └── tool
+ │ ├── do_all
+ │ ├── make
+ </RT-code>
+ <RT-code>
+ │ ├── makefile
+ │ ├── release
+ │ └── setup
+ ├── LICENSE
+ ├── scratchpad
+ │ └── Harmony__79f9d52__2026-03-07_085628Z.tar
+ ├── setup
+ ├── shared
+ │ ├── authored
+ </RT-code>
+ <RT-code>
+ │ ├── document
+ │ │ ├── install_generic.org
+ │ │ ├── install_Python.org
+ │ │ └── setup.js
+ │ ├── made
+ │ ├── style_directory_dict.js
+ │ ├── third_party
+ │ │ ├── RT-style-JS_public -> ../../../RT-style-JS_public/
+ │ │ └── upstream
+ </RT-code>
+ <RT-code>
+ │ └── tool
+ │ ├── scratchpad
+ │ ├── setup
+ │ ├── style
+ │ └── version
+ └── tester
+ ├── authored
+ │ └── test_routine.sh
+ ├── RT_Format
+ </RT-code>
+ <RT-code>
+ │ ├── RT_Format
+ │ ├── RT_Format.el
+ │ ├── test_0_data.c
+ │ └── test_1_data.py
+ └── tool
+ └── setup
+
+ 29 directories, 37 files
+ </RT-code>
+
+ </RT-article>
+ </body>
+</html>
--- /dev/null
+Copyright © 2019, 2024, 2025, 2026 Reasoning Technology. All Rights Reserved.
+
+This software, including all source code, compiled code, text, images, graphics, and associated media (collectively, "the Software and Content"), is the proprietary property of Reasoning Technology.
+
+A limited license, revocable at any time, is granted to access and view the Software and Content strictly for normal web browsing purposes.
+
+Beyond this limited viewing permission, no other rights are granted. A person is strictly prohibited from copying, extracting, modifying, republishing, distributing, sublicensing, selling, or otherwise exploiting this Software and Content, in whole or in part, for any purpose, without express written consent from Reasoning Technology. No license to any underlying technology, patents, trademarks, or other intellectual property is granted or implied by this access.
--- /dev/null
+window.RT_REPO_ROOT = "../";
+document.write('<script src="' + window.RT_REPO_ROOT + 'shared/style_directory_dict.js"></script>');
+document.write('<script src="' + window.RT_REPO_ROOT + 'shared/third_party/RT-style-JS_public/consumer/release/RT/core/loader.js"></script>');
+document.write('<script src="' + window.RT_REPO_ROOT + 'shared/third_party/RT-style-JS_public/consumer/release/RT/core/body_visibility_hidden.js"></script>');
# setup the project
#
- source shared/authored/setup
+ source shared/tool/setup
+ if [[ -f "shared/authored/setup" ]]; then
+ source shared/authored/setup
+ fi
# setup tools
#
# PATH
# precedence: last defined, first discovered
- PATH="$REPO_HOME/shared/third_party/RT-project-share/release/bash:$PATH"
- PATH="$REPO_HOME/shared/third_party/RT-project-share/release/amd64:$PATH"
- PATH="$REPO_HOME/shared/third_party:$PATH"
PATH="$REPO_HOME/shared/authored:$PATH"
PATH="$REPO_HOME/shared/made:$PATH"
+ PATH="$REPO_HOME/shared/tool:$PATH"
# Remove duplicates
clean_path() {
projects / Harmony / commitdiff