ceedling 1.1.9 → 1.2.0

data/site-local/development/workflow.html

@@ -14,7 +14,7 @@
         <link rel="prev" href="index.html">
       
       
-        <link rel="next" href="plugins/index.html">
+        <link rel="next" href="releases.html">
       
       
         
@@ -89,10 +89,34 @@
     </div>
     <div data-md-component="announce">
       
+        <aside class="md-banner">
+          <div class="md-banner__inner md-grid md-typeset">
+            
+            
+  
+
+          </div>
+          
+        </aside>
+      
     </div>
     
       <div data-md-color-scheme="default" data-md-component="outdated" hidden>
         
+          <aside class="md-banner md-banner--warning">
+            <div class="md-banner__inner md-grid md-typeset">
+              
+  
+    You are not viewing the latest version.
+    <a href="../..">
+      <strong>Click here to go to latest.</strong>
+    </a>
+  
+
+            </div>
+            <script>var el=document.querySelector("[data-md-component=outdated]"),base=new URL(".."),outdated=__md_get("__outdated",sessionStorage,base);!0===outdated&&el&&(el.hidden=!1)</script>
+          </aside>
+        
       </div>
     
     
@@ -330,7 +354,7 @@
     
     
       <li class="md-tabs__item">
-        <a href="../project/release-history.html" class="md-tabs__link">
+        <a href="../project/index.html" class="md-tabs__link">
           
   
   
@@ -641,6 +665,8 @@
         
       
         
+      
+        
       
         
       
@@ -788,6 +814,34 @@
   
   
   
+    <li class="md-nav__item">
+      <a href="../getting-started/builds.html" class="md-nav__link">
+        
+  
+  
+  <span class="md-ellipsis">
+    
+  
+    Builds
+  
+
+    
+  </span>
+  
+  
+
+      </a>
+    </li>
+  
+
+              
+            
+              
+                
+  
+  
+  
+  
     
     
       
@@ -814,7 +868,7 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3_5" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3_6" >
         
           
           <div class="md-nav__link md-nav__container">
@@ -836,14 +890,14 @@
             </a>
             
               
-              <label class="md-nav__link " for="__nav_3_5" id="__nav_3_5_label" tabindex="0">
+              <label class="md-nav__link " for="__nav_3_6" id="__nav_3_6_label" tabindex="0">
                 <span class="md-nav__icon md-icon"></span>
               </label>
             
           </div>
         
-        <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_3_5_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_3_5">
+        <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_3_6_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_3_6">
             <span class="md-nav__icon md-icon"></span>
             
   
@@ -2410,6 +2464,8 @@
         
       
         
+      
+        
       
         
       
@@ -3041,8 +3097,61 @@
   
   
     <li class="md-nav__item">
-      <a href="../plugins/bullseye.html" class="md-nav__link">
+      <a href="../plugins/sanitize.html" class="md-nav__link">
+        
+  
+  
+  <span class="md-ellipsis">
+    
+  
+    Sanitize (ASan, UBSan & Leaks)
+  
+
+    
+  </span>
+  
+  
+
+      </a>
+    </li>
+  
+
+              
+            
+              
+                
+  
+  
+  
+  
+    
+    
+      
+        
+          
+        
+      
+        
+      
+    
+    
+    
+      
+      
+        
+      
+    
+    
+    <li class="md-nav__item md-nav__item--nested">
+      
+        
         
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_6_13" >
+        
+          
+          <div class="md-nav__link md-nav__container">
+            <a href="../plugins/bullseye/index.html" class="md-nav__link ">
+              
   
   
   <span class="md-ellipsis">
@@ -3052,6 +3161,50 @@
   
 
     
+  </span>
+  
+  
+
+            </a>
+            
+              
+              <label class="md-nav__link " for="__nav_6_13" id="__nav_6_13_label" tabindex="0">
+                <span class="md-nav__icon md-icon"></span>
+              </label>
+            
+          </div>
+        
+        <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_6_13_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_6_13">
+            <span class="md-nav__icon md-icon"></span>
+            
+  
+    Bullseye (Coverage)
+  
+
+          </label>
+          <ul class="md-nav__list" data-md-scrollfix>
+            
+              
+            
+              
+                
+  
+  
+  
+  
+    <li class="md-nav__item">
+      <a href="../plugins/bullseye/licensing.html" class="md-nav__link">
+        
+  
+  
+  <span class="md-ellipsis">
+    
+  
+    Licensing
+  
+
+    
   </span>
   
   
@@ -3062,6 +3215,14 @@
 
               
             
+          </ul>
+        </nav>
+      
+    </li>
+  
+
+              
+            
               
                 
   
@@ -3531,6 +3692,12 @@
     
       
         
+          
+        
+      
+        
+      
+        
       
         
       
@@ -3550,8 +3717,9 @@
         <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_8" >
         
           
-          <label class="md-nav__link" for="__nav_8" id="__nav_8_label" tabindex="0">
-            
+          <div class="md-nav__link md-nav__container">
+            <a href="../project/index.html" class="md-nav__link ">
+              
   
   
   <span class="md-ellipsis">
@@ -3565,8 +3733,14 @@
   
   
 
-            <span class="md-nav__icon md-icon"></span>
-          </label>
+            </a>
+            
+              
+              <label class="md-nav__link " for="__nav_8" id="__nav_8_label" tabindex="0">
+                <span class="md-nav__icon md-icon"></span>
+              </label>
+            
+          </div>
         
         <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_8_label" aria-expanded="false">
           <label class="md-nav__title" for="__nav_8">
@@ -3580,6 +3754,8 @@
           <ul class="md-nav__list" data-md-scrollfix>
             
               
+            
+              
                 
   
   
@@ -3613,6 +3789,34 @@
   
   
   
+    <li class="md-nav__item">
+      <a href="../project/sbom.html" class="md-nav__link">
+        
+  
+  
+  <span class="md-ellipsis">
+    
+  
+    Software Bill of Materials
+  
+
+    
+  </span>
+  
+  
+
+      </a>
+    </li>
+  
+
+              
+            
+              
+                
+  
+  
+  
+  
     <li class="md-nav__item">
       <a href="../project/upgrade.html" class="md-nav__link">
         
@@ -3685,6 +3889,8 @@
         
       
         
+      
+        
       
         
       
@@ -3811,6 +4017,17 @@
     </label>
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
       
+        <li class="md-nav__item">
+  <a href="#code-organization" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Code organization
+      
+    </span>
+  </a>
+  
+</li>
+      
         <li class="md-nav__item">
   <a href="#installation-options" class="md-nav__link">
     <span class="md-ellipsis">
@@ -3915,6 +4132,28 @@
     </span>
   </a>
   
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#recording-a-dependencys-license" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Recording a dependency’s license
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#updating-a-vendored-component" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Updating a vendored component
+      
+    </span>
+  </a>
+  
 </li>
         
       </ul>
@@ -3934,54 +4173,266 @@
 </li>
       
         <li class="md-nav__item">
-  <a href="#documentation" class="md-nav__link">
+  <a href="#troubleshooting-system-tests" class="md-nav__link">
     <span class="md-ellipsis">
       
-        Documentation
+        Troubleshooting system tests
       
     </span>
   </a>
   
-</li>
-      
-        <li class="md-nav__item">
-  <a href="#bin-vs-lib" class="md-nav__link">
+    <nav class="md-nav" aria-label="Troubleshooting system tests">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#retained-artifacts" class="md-nav__link">
     <span class="md-ellipsis">
       
-        bin/ vs. lib/
+        Retained artifacts
       
     </span>
   </a>
   
 </li>
+        
+          <li class="md-nav__item">
+  <a href="#failure-output-at-the-console" class="md-nav__link">
+    <span class="md-ellipsis">
       
-    </ul>
-  
-</nav>
+        Failure output at the console
       
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
+    </span>
+  </a>
   
-    
-    
-      
-        
-          
-        
-      
+</li>
         
+          <li class="md-nav__item">
+  <a href="#artifacts-from-a-failed-ci-run" class="md-nav__link">
+    <span class="md-ellipsis">
       
-        
+        Artifacts from a failed CI run
       
-        
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#linting" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Linting
+      
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label="Linting">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#the-offense-backlog" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        The offense backlog
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#linting-in-continuous-integration" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Linting in continuous integration
+      
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#profiling" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Profiling
+      
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label="Profiling">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#reports" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Reports
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#reading-a-report" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Reading a report
+      
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#building-the-gem" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Building the gem
+      
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label="Building the gem">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#generating-the-bill-of-materials" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Generating the Bill of Materials
+      
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#documentation" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Documentation
+      
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label="Documentation">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#developer-documentation" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Developer documentation
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#user-documentation" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        User documentation
+      
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#bin-vs-lib" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        bin/ vs. lib/
+      
+    </span>
+  </a>
+  
+</li>
+      
+    </ul>
+  
+</nav>
+      
+    </li>
+  
+
+              
+            
+              
+                
+  
+  
+  
+  
+    <li class="md-nav__item">
+      <a href="releases.html" class="md-nav__link">
+        
+  
+  
+  <span class="md-ellipsis">
+    
+  
+    Branching & Releases
+  
+
+    
+  </span>
+  
+  
+
+      </a>
+    </li>
+  
+
+              
+            
+              
+                
+  
+  
+  
+  
+    
+    
+      
+        
+          
+        
+      
+        
+      
+        
+      
+        
       
     
     
@@ -3999,7 +4450,7 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_10_3" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_10_4" >
         
           
           <div class="md-nav__link md-nav__container">
@@ -4021,14 +4472,14 @@
             </a>
             
               
-              <label class="md-nav__link " for="__nav_10_3" id="__nav_10_3_label" tabindex="">
+              <label class="md-nav__link " for="__nav_10_4" id="__nav_10_4_label" tabindex="">
                 <span class="md-nav__icon md-icon"></span>
               </label>
             
           </div>
         
-        <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_10_3_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_10_3">
+        <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_10_4_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_10_4">
             <span class="md-nav__icon md-icon"></span>
             
   
@@ -4165,6 +4616,17 @@
     </label>
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
       
+        <li class="md-nav__item">
+  <a href="#code-organization" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Code organization
+      
+    </span>
+  </a>
+  
+</li>
+      
         <li class="md-nav__item">
   <a href="#installation-options" class="md-nav__link">
     <span class="md-ellipsis">
@@ -4269,6 +4731,28 @@
     </span>
   </a>
   
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#recording-a-dependencys-license" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Recording a dependency’s license
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#updating-a-vendored-component" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Updating a vendored component
+      
+    </span>
+  </a>
+  
 </li>
         
       </ul>
@@ -4285,6 +4769,162 @@
     </span>
   </a>
   
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#troubleshooting-system-tests" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Troubleshooting system tests
+      
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label="Troubleshooting system tests">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#retained-artifacts" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Retained artifacts
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#failure-output-at-the-console" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Failure output at the console
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#artifacts-from-a-failed-ci-run" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Artifacts from a failed CI run
+      
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#linting" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Linting
+      
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label="Linting">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#the-offense-backlog" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        The offense backlog
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#linting-in-continuous-integration" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Linting in continuous integration
+      
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#profiling" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Profiling
+      
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label="Profiling">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#reports" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Reports
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#reading-a-report" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Reading a report
+      
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#building-the-gem" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Building the gem
+      
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label="Building the gem">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#generating-the-bill-of-materials" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Generating the Bill of Materials
+      
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
 </li>
       
         <li class="md-nav__item">
@@ -4296,6 +4936,34 @@
     </span>
   </a>
   
+    <nav class="md-nav" aria-label="Documentation">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#developer-documentation" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Developer documentation
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#user-documentation" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        User documentation
+      
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
 </li>
       
         <li class="md-nav__item">
@@ -4378,6 +5046,23 @@
 
 
 <h1 id="ceedling-development">Ceedling development</h1>
+<h2 id="code-organization">Code organization</h2>
+<p>There are two top-level code directories:</p>
+<ol>
+<li><code>bin/</code> This is the “bootloader” that encompasses the command line 
+   handler and loading the project configuration including merging
+   Mixins. All applications commands are executed from within this
+   code (<a href="../getting-started/command-line.html">application commands are distinct from build/plugin tasks</a>).</li>
+<li><code>lib/ceedling/</code> This is the application itself. Major subsystems
+   are organized in subdirectories. Configuration processing happens
+   in the main application.</li>
+</ol>
+<p>The handoff from (1) to (2) involves:</p>
+<ol>
+<li>Triggering the loaded and merged configuration to undergo
+   processing, validation, and plugin loading.</li>
+<li>Triggering the build/plugin task named at the command line.</li>
+</ol>
 <h2 id="installation-options">Installation options</h2>
 <h3 id="local-installation">Local installation</h3>
 <p>After installing Ruby…</p>
@@ -4536,25 +5221,303 @@ automatically; if you ever invoke an RSpec or Ruby command directly
 instead of through a Rake task, prefix it with <code>bundle exec</code>:</p>
 <div class="highlight"><pre><span></span><code><a id="__codelineno-9-1" name="__codelineno-9-1" href="#__codelineno-9-1"></a><span class="w"> </span>&gt;<span class="w"> </span>bundle<span class="w"> </span><span class="nb">exec</span><span class="w"> </span>rspec<span class="w"> </span>spec/some_spec.rb
 </code></pre></div>
+<h3 id="recording-a-dependencys-license">Recording a dependency’s license</h3>
+<p>Changing a runtime dependency means recording its license. The generated
+<a href="../project/sbom.html">Software Bill of Materials</a> carries a license for every gem a user
+installs, and that comes from a curated list in <code>tools/sbom/gem_licenses.rb</code>
+rather than from <code>Gemfile.lock</code>.</p>
+<p>The list is curated because nothing else is accurate. <code>Gemfile.lock</code> records 
+no license at all. A gem’s own gemspec is unreliable, and project license 
+statements and conventions are often messy.</p>
+<p>Each curated entry records three things. The license is an SPDX identifier 
+or expression. <code>verified_for</code> is the version the license was read against.
+<code>source</code> names where it was read.</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-10-1" name="__codelineno-10-1" href="#__codelineno-10-1"></a><span class="s1">&#39;rake&#39;</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="p">{</span>
+<a id="__codelineno-10-2" name="__codelineno-10-2" href="#__codelineno-10-2"></a><span class="w">  </span><span class="ss">license</span><span class="p">:</span><span class="w"> </span><span class="s1">&#39;MIT&#39;</span><span class="p">,</span>
+<a id="__codelineno-10-3" name="__codelineno-10-3" href="#__codelineno-10-3"></a><span class="w">  </span><span class="ss">verified_for</span><span class="p">:</span><span class="w"> </span><span class="s1">&#39;13.2.1&#39;</span><span class="p">,</span>
+<a id="__codelineno-10-4" name="__codelineno-10-4" href="#__codelineno-10-4"></a><span class="w">  </span><span class="ss">source</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;the gem&#39;s own gemspec&quot;</span>
+<a id="__codelineno-10-5" name="__codelineno-10-5" href="#__codelineno-10-5"></a><span class="p">},</span>
+</code></pre></div>
+<p><code>rake sbom:build</code> refuses to run when the list and the resolved dependencies
+disagree. It reports three kinds of disagreement and names the remedy for each.</p>
+<ul>
+<li>A dependency arrived with no entry. Read its license and add one.</li>
+<li>An entry outlived its dependency. Remove it.</li>
+<li>A version moved away from the one its entry was verified against. Read the
+  license again, then update <code>license</code> and <code>verified_for</code> together.</li>
+</ul>
+<p>That third check is why <code>verified_for</code> exists. A license cannot be re-read
+without reaching the network, so a version change stands in for “worth reading
+again”. Because <code>Gemfile.lock</code> is generally curated by hand in this project,
+a version change is already a deliberate act, and this failure lands while 
+you are editing dependencies.</p>
+<p>One kind of drift escapes all three checks. A gem may change its license
+without changing version. <code>rake sbom:licenses:audit</code> compares the list against
+gems installed locally and reports anything that disagrees. It reads your
+machine rather than the repository, so it is advisory and deliberately outside
+<code>sbom:build</code>.</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-11-1" name="__codelineno-11-1" href="#__codelineno-11-1"></a><span class="w"> </span>&gt;<span class="w"> </span>rake<span class="w"> </span>sbom:licenses:audit
+</code></pre></div>
+<h3 id="updating-a-vendored-component">Updating a vendored component</h3>
+<p>Updating Unity, CMock, or CException needs no bookkeeping beyond the submodule
+itself. Each is identified in the SBOM by the commit it is pinned at, read from
+<code>git submodule status --recursive</code> at generation time.</p>
+<p>Vendored DIY and vendored fff are different, being plain directories rather than
+submodules. DIY’s version is read from its source. fff has no version of any
+kind upstream, and its lineage is recorded as constants in
+<code>tools/sbom/inventory.rb</code>. Changing either means updating those.</p>
 <h2 id="running-self-tests">Running self-tests</h2>
 <p>Ceedling uses <a href="https://rspec.info">RSpec</a> for its tests.</p>
 <p>To execute tests you may run the following from the root of your local 
 Ceedling repository. This test suite build option balances test coverage
 with suite execution time.</p>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-10-1" name="__codelineno-10-1" href="#__codelineno-10-1"></a><span class="w"> </span>&gt;<span class="w"> </span>rake<span class="w"> </span>spec
+<div class="highlight"><pre><span></span><code><a id="__codelineno-12-1" name="__codelineno-12-1" href="#__codelineno-12-1"></a><span class="w"> </span>&gt;<span class="w"> </span>rake<span class="w"> </span>spec
 </code></pre></div>
 <p>To run individual test files (Ceedling’s Ruby-based tests, that is) and 
 perform other tasks, use the available Rake tasks. From the root of your 
 local Ceedling repo, list those task like this:</p>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-11-1" name="__codelineno-11-1" href="#__codelineno-11-1"></a><span class="w"> </span>&gt;<span class="w"> </span>rake<span class="w"> </span>-T
+<div class="highlight"><pre><span></span><code><a id="__codelineno-13-1" name="__codelineno-13-1" href="#__codelineno-13-1"></a><span class="w"> </span>&gt;<span class="w"> </span>rake<span class="w"> </span>-T
 </code></pre></div>
+<h2 id="troubleshooting-system-tests">Troubleshooting system tests</h2>
+<p>System test failures are diagnosed from retained artifacts rather than from spec
+output alone. Each system spec deploys a real Ceedling installation into a
+temporary directory and runs real builds there. The RSpec failure reports which
+expectation failed. It does not report what the build under test actually did.</p>
+<p>Nothing is retained by default. A normal run deletes every temporary directory as
+it finishes, so a failure leaves no evidence behind.</p>
+<p>Two Rake tasks turn retention on.</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-14-1" name="__codelineno-14-1" href="#__codelineno-14-1"></a><span class="w"> </span>&gt;<span class="w"> </span>rake<span class="w"> </span>specs:system:debug
+<a id="__codelineno-14-2" name="__codelineno-14-2" href="#__codelineno-14-2"></a><span class="w"> </span>&gt;<span class="w"> </span>rake<span class="w"> </span>spec:system:debug:cli_surface
+</code></pre></div>
+<p><code>specs:system:debug</code> runs the whole suite and keeps failures only. Passing project
+directories are deleted as they finish, and passing logs are never written. This
+is the mode CI uses.</p>
+<p><code>spec:system:debug:&lt;name&gt;</code> runs one spec and keeps everything, pass and fail
+alike. Reach for it while working on a single spec.</p>
+<div class="admonition tip">
+<p class="admonition-title">Tip</p>
+<p><code>rake -T</code> advertises the family as <code>spec:system:debug:*</code>. Replace the wildcard
+with a spec name. <code>rake -AT spec:system:debug</code> lists every name it accepts.</p>
+</div>
+<p>Both tasks set <code>CEEDLING_SYSTEM_TEST_KEEP</code> on your behalf. Set it to <code>all</code> or
+<code>failures</code> yourself when driving RSpec directly.</p>
+<h3 id="retained-artifacts">Retained artifacts</h3>
+<p>Everything retained lands under <code>specout/</code> in the repository root.</p>
+<table>
+<thead>
+<tr>
+<th>Path</th>
+<th>Contents</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>specout/proj/fail/</code></td>
+<td>Deployed project directory for each failing spec</td>
+</tr>
+<tr>
+<td><code>specout/proj/pass/</code></td>
+<td>The same for passing specs, in <code>all</code> mode only</td>
+</tr>
+<tr>
+<td><code>specout/fail.&lt;description&gt;.&lt;pid&gt;-&lt;timestamp&gt;.log</code></td>
+<td>Captured console output of a failing spec</td>
+</tr>
+<tr>
+<td><code>specout/pass.&lt;description&gt;.&lt;pid&gt;-&lt;timestamp&gt;.log</code></td>
+<td>The same for passing specs, in <code>all</code> mode only</td>
+</tr>
+</tbody>
+</table>
+<p>Each log opens with the command that produced it, followed by that command's
+combined stdout and stderr.</p>
+<p>Each retained project directory is a complete deployment, including the vendored
+Ceedling the spec installed. This is where to reproduce a failure by hand. Change
+into it and run the same <code>ceedling</code> command the log names.</p>
+<h3 id="failure-output-at-the-console">Failure output at the console</h3>
+<p>A failing spec prints a diagnostic block to stderr before the suite continues. The
+block names the temporary directory, names the log file, and summarizes the
+captured output.</p>
+<p>The summary carries only what is worth reading first. It collects every line
+containing <code>ERROR</code> or <code>EXCEPTION</code>, the whole of stderr, any debug backtrace, and
+the failed and overall test summaries. Full output stays in the log file.</p>
+<h3 id="artifacts-from-a-failed-ci-run">Artifacts from a failed CI run</h3>
+<p>CI uploads the same directory whenever a test job fails. Download it from the
+workflow run's summary page.</p>
+<p>Artifacts are named <code>specout-failures-&lt;os&gt;-ruby-&lt;version&gt;</code>. The two specialized
+jobs add <code>specout-failures-locale-ruby-3.3</code> and
+<code>specout-failures-encoding-stress-ruby-3.3</code>.</p>
+<p>CI runs in <code>failures</code> mode, so an artifact holds only failure data.</p>
+<h2 id="linting">Linting</h2>
+<p>Ceedling lints its own Ruby with <a href="https://rubocop.org">RuboCop</a>. Four departments are enforced. Lint
+and Security catch defects. Metrics tracks complexity. Performance flags
+avoidable allocations and slower idioms.</p>
+<p>Style, Layout, and Naming are deliberately not enforced. Those departments encode
+taste rather than defects, and applying them would rewrite nearly every call site
+in the project to no benefit. ThrowTheSwitch's house style is described in prose
+in the coding standard instead.</p>
+<p>Configuration lives in <code>.rubocop.yml</code> at the root of the repository. Every
+decision in that file is commented, including the cops deliberately turned down
+and the reasoning for each.</p>
+<p>The linting gems are not installed by an ordinary <code>bundle install</code>. Install them
+once with the setup task.</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-15-1" name="__codelineno-15-1" href="#__codelineno-15-1"></a><span class="w"> </span>&gt;<span class="w"> </span>rake<span class="w"> </span>lint:setup
+</code></pre></div>
+<p>Then lint the whole project, or only the files your branch changed.</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-16-1" name="__codelineno-16-1" href="#__codelineno-16-1"></a><span class="w"> </span>&gt;<span class="w"> </span>rake<span class="w"> </span>lint
+<a id="__codelineno-16-2" name="__codelineno-16-2" href="#__codelineno-16-2"></a><span class="w"> </span>&gt;<span class="w"> </span>rake<span class="w"> </span>lint:changed
+<a id="__codelineno-16-3" name="__codelineno-16-3" href="#__codelineno-16-3"></a><span class="w"> </span>&gt;<span class="w"> </span>rake<span class="w"> </span><span class="s2">&quot;lint:changed[master]&quot;</span>
+</code></pre></div>
+<p><code>lint:changed</code> is the faster loop while working on a branch. It compares against
+<code>next_version</code> unless you name another branch or revision. Quote the task name so
+your shell does not interpret the brackets.</p>
+<p>Changed files include both commits on your branch and uncommitted work in your
+tree. Naming a branch that does not exist is an error rather than an empty
+result.</p>
+<p>RuboCop can correct some offenses itself. Only safe corrections are applied.
+Review the resulting diff before keeping it.</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-17-1" name="__codelineno-17-1" href="#__codelineno-17-1"></a><span class="w"> </span>&gt;<span class="w"> </span>rake<span class="w"> </span>lint:fix
+</code></pre></div>
+<p>Metrics offenses are never autocorrectable, so this task mostly touches
+Performance cops.</p>
+<h3 id="the-offense-backlog">The offense backlog</h3>
+<p>A passing <code>rake lint</code> means no <em>new</em> offenses rather than zero offenses.</p>
+<p><code>.rubocop_todo.yml</code> records the offenses that already existed when RuboCop was
+adopted. Without that file every run would report all of them and bury anything 
+newly introduced.</p>
+<p>The file is generated, and it is meant to shrink. Removing records as the
+underlying code improves is the entire point of baselining. Regenerate the file
+after an improvement rather than editing it by hand.</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-18-1" name="__codelineno-18-1" href="#__codelineno-18-1"></a><span class="w"> </span>&gt;<span class="w"> </span>rake<span class="w"> </span>lint:todo
+</code></pre></div>
+<p>A decision to live with a cop permanently does not belong in the backlog. Those
+belong in <code>.rubocop.yml</code>, with a comment explaining why the cop is wrong for this
+project.</p>
+<h3 id="linting-in-continuous-integration">Linting in continuous integration</h3>
+<p>CI runs <code>rake lint</code> on every pull request. Findings appear as annotations
+directly on the changed lines of the diff.</p>
+<p>The job is advisory. It reports findings without failing the build.</p>
+<p>That is a starting position rather than the intent. The backlog is still large
+enough that a new offense is unremarkable, so blocking would obstruct more than
+it would protect. The job becomes blocking once the backlog has shrunk far enough
+that any finding is a genuine surprise.</p>
+<h2 id="profiling">Profiling</h2>
+<p>Profiling answers where a Ceedling build spends its time. It samples a real build
+of a real example project with <a href="https://github.com/tmm1/stackprof">StackProf</a> and renders a flame graph.</p>
+<p>The profiling gem is not installed by an ordinary <code>bundle install</code>. Install it
+once with the setup task.</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-19-1" name="__codelineno-19-1" href="#__codelineno-19-1"></a><span class="w"> </span>&gt;<span class="w"> </span>rake<span class="w"> </span>profile:setup
+</code></pre></div>
+<p>Then profile any example project against any Ceedling build task.</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-20-1" name="__codelineno-20-1" href="#__codelineno-20-1"></a><span class="w"> </span>&gt;<span class="w"> </span>rake<span class="w"> </span><span class="s2">&quot;profile:run[temp_sensor,test:all]&quot;</span>
+<a id="__codelineno-20-2" name="__codelineno-20-2" href="#__codelineno-20-2"></a><span class="w"> </span>&gt;<span class="w"> </span>rake<span class="w"> </span><span class="s2">&quot;profile:run[temp_sensor,clobber test:all]&quot;</span>
+</code></pre></div>
+<p>The first argument names a project under <code>examples/</code>. The choices are
+<code>cipher_quest</code>, <code>temp_sensor</code>, and <code>wondrous_forest</code>. The second argument is
+whatever you would type after <code>ceedling</code>. Quote the task name so your shell does
+not interpret the brackets.</p>
+<h3 id="reports">Reports</h3>
+<p>Three files land in <code>tmp/profiling/&lt;project&gt;/reports/</code>, each named by timestamp.</p>
+<table>
+<thead>
+<tr>
+<th>Extension</th>
+<th>Contents</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>.txt</code></td>
+<td>Ranked list of the hottest frames</td>
+</tr>
+<tr>
+<td><code>.html</code></td>
+<td>Interactive flame graph</td>
+</tr>
+<tr>
+<td><code>.dump</code></td>
+<td>Raw StackProf data, for your own queries</td>
+</tr>
+</tbody>
+</table>
+<p>Timestamps keep successive runs from overwriting one another. A full build followed
+by a no-op rebuild produces two comparable sets.</p>
+<h3 id="reading-a-report">Reading a report</h3>
+<p>Profiling runs single threaded, and that is deliberate. The task pins both thread
+counts to 1 so the work stays on the thread StackProf samples. A multi-threaded run
+would hide most of the build in worker threads the profiler never sees. No flame
+graph this task produces says anything about thread contention.</p>
+<p>Expect <code>Kernel#sleep</code> and <code>Thread#value</code> to dominate every report. They represent
+time spent waiting on child processes rather than work done in Ruby. Read past
+them to the frames underneath.</p>
+<p>The scaffolded project persists between runs. <code>profile:run</code> copies the example into
+<code>tmp/profiling/&lt;project&gt;/</code> on first use and leaves it there, build directory and
+dependency cache included. A second run against the same project therefore
+profiles a real incremental build. Delete <code>tmp/profiling/&lt;project&gt;/</code> to start from
+a clean scaffold.</p>
+<div class="admonition note">
+<p class="admonition-title">Note</p>
+<p>Profiling is unavailable on Windows. StackProf builds a native extension that
+does not compile there, so <code>profile:setup</code> declines with a message rather than
+attempting it.</p>
+</div>
+<h2 id="building-the-gem">Building the gem</h2>
+<p>Building the gem locally shows what a release would actually contain. The gemspec
+assembles its file list by sweeping the working tree, so a local build reflects
+whatever happens to be lying around.</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-21-1" name="__codelineno-21-1" href="#__codelineno-21-1"></a><span class="w"> </span>&gt;<span class="w"> </span>rake<span class="w"> </span>gem:build
+<a id="__codelineno-21-2" name="__codelineno-21-2" href="#__codelineno-21-2"></a><span class="w"> </span>&gt;<span class="w"> </span>rake<span class="w"> </span>gem:clean
+</code></pre></div>
+<p><code>gem:build</code> runs the same <code>gem build ceedling.gemspec</code> that CI runs and leaves
+<code>ceedling-&lt;version&gt;.gem</code> in the repository root. <code>gem:clean</code> removes built gems.</p>
+<p>The version carries a <code>.dev</code> suffix, so a local build is named
+<code>ceedling-&lt;version&gt;.dev.gem</code>. <code>lib/version.rb</code> appends that marker to every build
+the release pipeline did not produce, which is also why <code>ceedling version</code> reports
+it. See <a href="releases.html">Branching &amp; Releases</a> for how a release build clears it.</p>
+<p><code>gem:build</code> depends on <code>gem:clean</code>, which matters more than it appears to. The
+gemspec has no exclusion for <code>.gem</code> files, so a gem left from an earlier build
+would be packaged inside the next one.</p>
+<div class="admonition note">
+<p class="admonition-title">Note</p>
+<p>A local build omits the offline documentation bundle unless <code>site-local/</code>
+already exists. CI builds that bundle first. Run <code>rake docs:build:local</code> to
+match it.</p>
+</div>
+<h3 id="generating-the-bill-of-materials">Generating the Bill of Materials</h3>
+<p><code>rake sbom:build</code> writes both <a href="../project/sbom.html">Software Bill of Materials</a> documents into
+the repository root. A release generates them the same way.</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-22-1" name="__codelineno-22-1" href="#__codelineno-22-1"></a><span class="w"> </span>&gt;<span class="w"> </span>rake<span class="w"> </span>sbom:build
+<a id="__codelineno-22-2" name="__codelineno-22-2" href="#__codelineno-22-2"></a><span class="w"> </span>&gt;<span class="w"> </span>rake<span class="w"> </span>sbom:specs
+</code></pre></div>
+<p>The documents are never committed, and two mechanisms keep them out. <code>.gitignore</code>
+covers them, and the gemspec rejects them so a local build cannot package one
+into the gem it describes.</p>
+<p>A local document names a development version, for the same reason a locally built
+gem does. The release version is stamped during the release build.</p>
+<p>Unpack the result to inspect it.</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-23-1" name="__codelineno-23-1" href="#__codelineno-23-1"></a><span class="w"> </span>&gt;<span class="w"> </span>gem<span class="w"> </span>unpack<span class="w"> </span>ceedling-1.2.0.gem
+</code></pre></div>
+<p>The packaged gem deliberately carries <code>spec/</code>, <code>Gemfile</code>, <code>Gemfile.lock</code>, and
+<code>.rspec</code>. External tooling runs Ceedling's own suites against the released gem
+as part of validating installations and environments. These files make that 
+possible.</p>
+<p>Development-only tasks refuse to run from an unpacked gem. Profiling, linting, and
+the gem tasks each need repository files the gem does not carry, so they report
+that rather than failing on a missing file. The <code>specs:*</code> tasks and
+<code>coverage:report</code> work as normal.</p>
 <h2 id="documentation">Documentation</h2>
-<p>Ceedling’s documentation is built with <a href="https://www.mkdocs.org">MkDocs</a> + <a href="https://squidfunk.github.io/mkdocs-material/">Material theme</a> and versioned
+<h3 id="developer-documentation">Developer documentation</h3>
+<p>The Ceedling codebase is <a href="#code-organization">organized in directories</a>.</p>
+<p>Major subsystems are organized in directories. Most directories include detailed
+Markdown documents that provide both high-level overviews and detailed breakdowns
+of the subsystem.</p>
+<h3 id="user-documentation">User documentation</h3>
+<p>Ceedling’s user documentation is built with <a href="https://www.mkdocs.org">MkDocs</a> + <a href="https://squidfunk.github.io/mkdocs-material/">Material theme</a> and versioned
 with <a href="https://github.com/jimporter/mike">mike</a>. All Markdown source lives under <code>docs/mkdocs/</code>. The public site 
 configuration is in <code>mkdocs.yml</code> while the local site bundle configuration is in
 <code>mkdocs.local.yml</code>.</p>
 <p><strong>First-time setup</strong> (installs MkDocs, Material, and mike into the container):</p>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-12-1" name="__codelineno-12-1" href="#__codelineno-12-1"></a><span class="w"> </span>&gt;<span class="w"> </span>rake<span class="w"> </span>docs:install
+<div class="highlight"><pre><span></span><code><a id="__codelineno-24-1" name="__codelineno-24-1" href="#__codelineno-24-1"></a><span class="w"> </span>&gt;<span class="w"> </span>rake<span class="w"> </span>docs:install
 </code></pre></div>
 <p><strong>Available Rake tasks:</strong></p>
 <table>
@@ -4578,12 +5541,28 @@ configuration is in <code>mkdocs.yml</code> while the local site bundle configur
 <td>Build the site to be served in strict mode — fails on broken links or warnings</td>
 </tr>
 <tr>
+<td><code>rake docs:build:prerelease</code></td>
+<td>Build the prerelease site in strict mode, for local validation</td>
+</tr>
+<tr>
 <td><code>rake docs:serve</code></td>
 <td>Serve plain MkDocs site locally on port 8000</td>
 </tr>
 <tr>
-<td><code>rake docs:deploy</code></td>
-<td>Deploy <code>dev</code> version to local <code>gh-pages</code> branch (no remote push)</td>
+<td><code>rake docs:serve:prerelease</code></td>
+<td>Serve the prerelease site locally on port 8000, for docs development</td>
+</tr>
+<tr>
+<td><code>rake docs:deploy:prerelease[version]</code></td>
+<td>Deploy a prerelease build to Github Pages under <code>version</code> (usage: <code>rake docs:deploy:prerelease[1.2.0]</code>)</td>
+</tr>
+<tr>
+<td><code>rake docs:deploy:release[version]</code></td>
+<td>Deploy a release build to Github Pages under <code>version</code>, without changing <code>latest</code> (usage: <code>rake docs:deploy:release[1.1.0]</code>)</td>
+</tr>
+<tr>
+<td><code>rake docs:deploy:release:latest[version]</code></td>
+<td>Deploy a release build to Github Pages under <code>version</code> and set it as <code>latest</code> (usage: <code>rake docs:deploy:release:latest[1.2.0]</code>)</td>
 </tr>
 <tr>
 <td><code>rake docs:preview</code></td>
@@ -4594,7 +5573,7 @@ configuration is in <code>mkdocs.yml</code> while the local site bundle configur
 <p><strong>Browser preview in VS Code:</strong> When <code>mkdocs serve</code> or <code>mike serve</code> binds to 
 port 8000, VS Code detects it and shows a notification. The <strong>Ports</strong> panel also
 provides an <strong>Open in Browser</strong> button.</p>
-<p><strong>Hosted site:</strong> <a href="https://throwtheswitch.github.io/Ceedling/">https://throwtheswitch.github.io/Ceedling/</a></p>
+<p><strong>Hosted site:</strong> <a href="https://docs.throwtheswitch.org/Ceedling/">https://docs.throwtheswitch.org/Ceedling/</a></p>
 <h2 id="bin-vs-lib"><code>bin/</code> vs. <code>lib/</code></h2>
 <p>Most of Ceedling’s functionality is contained in the application code residing 
 in <code>lib/</code>. Ceedling’s command line handling, startup configuration, project