plucked a couple of nits before they got into the relay contacts

diff --git a/administrator/document/how-to_release.html b/administrator/document/how-to_release.html
index 3e9d644..08d5ec2 100644 (file)
--- a/administrator/document/how-to_release.html
+++ b/administrator/document/how-to_release.html
@@ -57,7 +57,7 @@
         The administrator tags the new commit with the full version number, such as <RT-code>v&lt;major&gt;.&lt;minor&gt;</RT-code>. Minor versions are edits on the major release branch. They are visible to a person by running the version command.
       </p>
       <p>
-        The developer must ensure the fix is also ported to the <RT-code>core_developer_branch</RT-code>. This prevents the defect from reappearing in future major releases.
+        The developer must ensure the fix is also ported to the <RT-code>core-developer_branch</RT-code>. This prevents the defect from reappearing in future major releases.
       </p>
 
       <h1>Tag and push</h1>

diff --git a/administrator/tool/new-project b/administrator/tool/new-project
index 58d49e3..c5b557e 100755 (executable)
--- a/administrator/tool/new-project
+++ b/administrator/tool/new-project
@@ -1,10 +1,27 @@
 #!/usr/bin/env python3
 # -*- mode: python; coding: utf-8; python-indent-offset: 2; indent-tabs-mode: nil -*-
 
+"""
+new-project
+
+This administrative tool instantiates a fresh project workspace modeled after
+the Harmony skeleton architecture.
+
+The script executes the following sequential lifecycle:
+  1. Validates the execution environment (requires an active role session).
+  2. Safely extracts a clean copy of all Git-tracked files using an archive stream.
+  3. Renames the boilerplate 0pus_Harmony anchor file to reflect the new project.
+  4. Injects an initial version tracking entry into the shared configuration space.
+  5. Initializes a fresh Git repository bound to the core_developer_branch.
+  6. Stages and commits the pristine skeleton infrastructure as a baseline.
+  7. Maps any upstream remote network targets passed via CLI parameters.
+"""
+
 import sys ,os ,subprocess
 from pathlib import Path
 
 def get_Z_date() -> str:
+  """Retrieves the current date utilizing the system Z timestamp tool."""
   try:
     res = subprocess.run(["Z" ,"format-%year-%month-%day"] ,capture_output=True ,text=True ,check=True)
     return res.stdout.strip()
@@ -12,6 +29,7 @@ def get_Z_date() -> str:
     return "1970-01-01"
 
 def work(project_name: str ,remotes: list[str]) -> int:
+  """Orchestrates the structural assembly of the new skeleton instance."""
   repo_home = os.environ.get("REPO_HOME")
   if not repo_home:
     print("Error: REPO_HOME is not set. A person must run this from within a sourced role environment." ,file=sys.stderr)
@@ -19,6 +37,7 @@ def work(project_name: str ,remotes: list[str]) -> int:
 
   repo_path = Path(repo_home).resolve()
   
+  # Resolve destination relative to the parent space of the current repository
   dest_path = Path(project_name)
   if not dest_path.is_absolute():
     dest_path = (repo_path.parent / project_name).resolve()
@@ -27,20 +46,23 @@ def work(project_name: str ,remotes: list[str]) -> int:
     print(f"Error: Destination {dest_path} already exists." ,file=sys.stderr)
     return 1
 
-  print(f"Creating new project at: {dest_path}")
+  print(f"Making new project at: {dest_path}")
   dest_path.mkdir(parents=True)
   
+  # Export tracked files without duplicating untracked scratchpads or git histories
   archive_cmd = "git archive HEAD | tar -x -C " + str(dest_path)
   res = subprocess.run(archive_cmd ,shell=True ,cwd=str(repo_path))
   if res.returncode != 0:
     print("Error extracting archive." ,file=sys.stderr)
     return 1
 
+  # Personalize the project baseline anchor file
   opus_src = dest_path / "0pus_Harmony"
   opus_dst = dest_path / f"0pus_{dest_path.name}"
   if opus_src.exists():
     opus_src.rename(opus_dst)
 
+  # Record the structural lineage in the shared version history
   version_file = dest_path / "shared" / "tool" / "version"
   date_str = get_Z_date()
   version_line = f"echo \"{dest_path.name} v0.1 {date_str}\"\n"
@@ -52,11 +74,13 @@ def work(project_name: str ,remotes: list[str]) -> int:
     with open(version_file ,"w" ,encoding="utf-8") as vf:
       vf.write(version_line)
 
+  # Initialize the pristine Git environment tracking system
   print("Initializing git repository...")
-  subprocess.run(["git" ,"init" ,"-b" ,"core-developer_branch"] ,cwd=str(dest_path) ,check=True)
+  subprocess.run(["git" ,"init" ,"-b" ,"core_developer_branch"] ,cwd=str(dest_path) ,check=True)
   subprocess.run(["git" ,"add" ,"."] ,cwd=str(dest_path) ,check=True)
   subprocess.run(["git" ,"commit" ,"-m" ,f"Initial commit of {dest_path.name} from Harmony skeleton"] ,cwd=str(dest_path) ,check=True)
 
+  # Configure structural tracking addresses for upstreams
   for idx ,remote_url in enumerate(remotes):
     remote_name = f"remote_{idx}"
     if "github.com" in remote_url: 
@@ -69,10 +93,11 @@ def work(project_name: str ,remotes: list[str]) -> int:
     print(f"Adding remote '{remote_name}': {remote_url}")
     subprocess.run(["git" ,"remote" ,"add" ,remote_name ,remote_url] ,cwd=str(dest_path) ,check=True)
 
-  print(f"Project '{dest_path.name}' successfully created.")
+  print(f"Project '{dest_path.name}' successfully made.")
   return 0
 
 def CLI(argv=None) -> int:
+  """Parses user input tokens from the shell execution frame."""
   if argv is None:
     argv = sys.argv[1:]