@davmash/bygone 0.8.13 → 0.8.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davmash/bygone",
-  "version": "0.8.13",
+  "version": "0.8.16",
   "description": "See how change happened. Visual diff and file history.",
   "author": "David Mashburn",
   "license": "MIT",

package/schemas/change-tour-source.schema.json

@@ -7,7 +7,7 @@
   "additionalProperties": false,
   "required": ["version", "anchors", "connections", "chapters"],
   "properties": {
-    "version": { "const": 1 },
+    "version": { "enum": [1, 2] },
     "title": { "$ref": "#/$defs/nonEmptyString" },
     "windowTitle": {
       "$ref": "#/$defs/nonEmptyString",
@@ -58,6 +58,46 @@
       "items": { "$ref": "#/$defs/chapter" }
     }
   },
+  "allOf": [
+    {
+      "if": { "properties": { "version": { "const": 1 } }, "required": ["version"] },
+      "then": {
+        "properties": {
+          "chapters": {
+            "items": {
+              "properties": {
+                "scenes": {
+                  "items": {
+                    "if": { "properties": { "kind": { "const": "stacked-diff" } }, "required": ["kind"] },
+                    "then": { "properties": { "stack": { "minItems": 3 } } }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    {
+      "if": { "properties": { "version": { "const": 2 } }, "required": ["version"] },
+      "then": {
+        "properties": {
+          "chapters": {
+            "items": {
+              "properties": {
+                "scenes": {
+                  "items": {
+                    "if": { "properties": { "kind": { "const": "deconstructed-diff" } }, "required": ["kind"] },
+                    "then": { "required": ["stack", "steps"] }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  ],
   "$defs": {
     "nonEmptyString": { "type": "string", "minLength": 1 },
     "stringArray": {
@@ -106,6 +146,18 @@
         "takeaway": { "$ref": "#/$defs/nonEmptyString" }
       }
     },
+    "requirement": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "text"],
+      "properties": {
+        "id": { "$ref": "#/$defs/nonEmptyString" },
+        "text": { "$ref": "#/$defs/nonEmptyString" },
+        "status": { "enum": ["fulfilled", "gap"] },
+        "source": { "$ref": "#/$defs/nonEmptyString" },
+        "confidence": { "enum": ["high", "medium", "low"] }
+      }
+    },
     "step": {
       "type": "object",
       "additionalProperties": false,
@@ -116,7 +168,8 @@
         "body": { "$ref": "#/$defs/nonEmptyString" },
         "focus": { "$ref": "#/$defs/nonEmptyString" },
         "connection": { "$ref": "#/$defs/nonEmptyString" },
-        "depth": { "enum": ["mentioned", "explained", "contextualized"] }
+        "depth": { "enum": ["mentioned", "explained", "contextualized"] },
+        "requirement": { "$ref": "#/$defs/requirement" }
       }
     },
     "coverageExclusion": {
@@ -194,7 +247,7 @@
         "bullets": { "$ref": "#/$defs/stringArray" },
         "tags": { "$ref": "#/$defs/stringArray" },
         "takeaway": { "$ref": "#/$defs/nonEmptyString" },
-        "stack": { "type": "array", "minItems": 3, "maxItems": 6, "items": { "$ref": "#/$defs/stackEntry" } },
+        "stack": { "type": "array", "minItems": 2, "maxItems": 6, "items": { "$ref": "#/$defs/stackEntry" } },
         "files": { "$ref": "#/$defs/stringArray" },
         "steps": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/stackStep" } }
       }
@@ -255,6 +308,8 @@
         "takeaway": { "$ref": "#/$defs/nonEmptyString" },
         "base": { "$ref": "#/$defs/nonEmptyString" },
         "target": { "$ref": "#/$defs/nonEmptyString" },
+        "stack": { "type": "array", "minItems": 2, "maxItems": 6, "items": { "$ref": "#/$defs/stackEntry" } },
+        "steps": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/step" } },
         "stages": {
           "type": "array",
           "minItems": 1,

package/skills/pr-tour-guide/SKILL.md

@@ -164,12 +164,13 @@ Retrieve the current contract:
 bygone tour schema > /tmp/change-tour-source.schema.json
 ```
 
-Write a `.bygone` file. The legacy `.bygone.yaml` spelling remains valid when
-generic YAML tooling requires it. Treat either authored source as Git-backed,
-not portable: pin `range.base` and `range.head` to the exact OIDs from the
-context, and keep the file within the corresponding repository so Bygone can
-resolve those objects. Use a compiled `.tour.json` only when a portable
-snapshot is required.
+Write a version 2 `.bygone` file. The legacy `.bygone.yaml` spelling remains
+valid when generic YAML tooling requires it. Treat the authored source and its
+compiled `.tour.json` as Git-backed, non-portable artifacts: pin `range.base`
+and `range.head` to the exact OIDs from the context, and keep them with the
+corresponding repository so Bygone can resolve those objects and live history.
+For every deconstructed scene, author the underlying real `stack` explicitly;
+do not infer it from the synthetic explanation stages or Git history.
 
 Set optional `windowTitle` when the tour should appear in the native window
 title — for example a pull request number (`PR-1234`) so multiple open tours
@@ -184,6 +185,13 @@ For every step:
 - connect behavior to tests, error handling, or other concrete proof;
 - add a connection only when the relationship between two locations materially improves understanding.
 
+Keep deconstructed-tour coordinates distinct:
+
+- A **stage** is a conceptual phase or cumulative comparison state; a **tour step** is one navigable explanation item within that stage.
+- Do not refer to either by an unqualified ordinal such as "Stage 2" or "Step 11" in authored titles, summaries, narration, or takeaways. Prefer the stable descriptive title so the reference survives edits.
+- When an ordinal is necessary, qualify the coordinate: "stage 2 of 4" versus "tour step 11 of 46."
+- Treat presenter-generated labels as UI context; do not repeat them in authored prose unless the distinction itself needs explanation.
+
 Never emit generated line numbers or hunk indexes. Verify candidate snippets against the pinned object when uncertain:
 
 ```sh
@@ -212,6 +220,7 @@ Treat this as a required self-audit, not a claim the validator can prove. For ea
 - tests are connected to the behavior they prove;
 - connections express causal, contractual, data-flow, ordering, or proof relationships;
 - binary files and omitted patches are surfaced explicitly;
+- deconstructed tours contain no unqualified "Stage N" or "Step N" references, and comparison stages and navigable tour steps use distinct nouns;
 - the final step supplies proof or a clear reviewer conclusion.
 
 ## Always print the open command
@@ -236,7 +245,7 @@ Tour tooling that does not open the app (`tour context`, `tour validate`, `tour
 
 ## Compile or present
 
-Compile a portable manifest when the user needs an artifact:
+Compile a repository-bound manifest when the user needs an artifact:
 
 ```sh
 bygone tour compile review.bygone --output review.tour.json

package/standalone/index.html

@@ -168,6 +168,11 @@
                     </div>
                 </div>
                 <div id="directory-diff" class="dir-view hidden">
+                    <div id="directory-view-tabs" class="directory-view-tabs" hidden>
+                        <button id="directory-overview-tab" type="button" title="Show change overview" aria-pressed="true">Overview</button>
+                        <button id="directory-files-tab" type="button" title="Show all changed files" aria-pressed="false">Files</button>
+                    </div>
+                    <section id="directory-overview" class="directory-overview" aria-label="Change overview" hidden></section>
                     <div class="dir-headers">
                         <div class="dir-col-header" id="dir-left-header">Left</div>
                         <div class="dir-header-gutter" aria-hidden="true"></div>

package/web/index.html

@@ -12,11 +12,19 @@
         <header class="tour-overview">
             <button id="tour-sidebar-hide" class="tour-sidebar-hide" type="button" title="Hide tour sidebar" aria-label="Hide tour sidebar">‹</button>
             <h1 id="tour-title"></h1>
+            <div id="tour-mode-controls" class="tour-mode-controls" hidden>
+                <label for="tour-mode-select">Mode</label>
+                <select id="tour-mode-select"></select>
+                <label for="tour-history-select" id="tour-history-label" hidden>Revision</label>
+                <select id="tour-history-select" hidden></select>
+                <div id="tour-mode-status" role="status" aria-live="polite"></div>
+            </div>
             <a id="tour-source" class="tour-source" target="_blank" rel="noreferrer" hidden>Open source ↗</a>
             <div class="tour-meta">
                 <div id="tour-range" class="tour-range"></div>
                 <div id="tour-stats" class="tour-stats"></div>
             </div>
+            <div id="tour-authoring-coverage" class="tour-authoring-coverage" aria-label="Tour authoring coverage" hidden></div>
         </header>
         <section class="tour-search" aria-label="Search tour">
             <div class="tour-search-controls">
@@ -99,6 +107,7 @@
             <div class="tour-narrative-side">
                 <div id="tour-step" class="tour-step" hidden>
                     <div id="tour-step-title" class="tour-step-title"></div>
+                    <div id="tour-step-requirement" class="tour-step-requirement" hidden></div>
                     <p id="tour-step-body" class="tour-step-body"></p>
                     <div id="tour-connection" class="tour-connection" hidden></div>
                 </div>
@@ -279,6 +288,11 @@
                     </div>
                 </div>
                 <div id="directory-diff" class="dir-view hidden">
+                    <div id="directory-view-tabs" class="directory-view-tabs" hidden>
+                        <button id="directory-overview-tab" type="button" title="Show change overview" aria-pressed="true">Overview</button>
+                        <button id="directory-files-tab" type="button" title="Show all changed files" aria-pressed="false">Files</button>
+                    </div>
+                    <section id="directory-overview" class="directory-overview" aria-label="Change overview" hidden></section>
                     <div class="dir-headers">
                         <div class="dir-col-header" id="dir-left-header">Left</div>
                         <div class="dir-header-gutter" aria-hidden="true"></div>

package/web/presenter.css

@@ -10,6 +10,13 @@
     --tour-narrative-height: 296px;
 }
 
+.tour-mode-controls { display: grid; gap: 6px; margin: 12px 0; }
+.tour-mode-controls[hidden], .tour-mode-controls [hidden] { display: none; }
+.tour-mode-controls select { width: 100%; min-width: 0; padding: 6px; color: var(--tour-body); background: var(--tour-surface); border: 1px solid var(--tour-border); border-radius: 4px; font: inherit; }
+#tour-mode-status { color: var(--tour-muted); }
+body.tour-derived-mode { --tour-narrative-height: 0px; }
+body.tour-derived-mode #tour-narrative { display: none; }
+
 .tour-shell {
     position: fixed;
     inset: 0 auto 0 0;
@@ -134,6 +141,10 @@ body.tour-mode.tour-discussion #container {
     text-decoration: none;
 }
 
+.tour-source[hidden] {
+    display: none;
+}
+
 .tour-source:hover {
     color: #fff;
 }
@@ -158,6 +169,59 @@ body.tour-mode.tour-discussion #container {
     white-space: nowrap;
 }
 
+.tour-authoring-coverage {
+    display: grid;
+    gap: 8px;
+    margin-top: 12px;
+}
+
+.tour-authoring-coverage[hidden] {
+    display: none;
+}
+
+.tour-coverage-item {
+    display: grid;
+    gap: 5px;
+    padding-left: 8px;
+    border-left: 2px solid var(--tour-accent-bright);
+}
+
+.tour-coverage-item[data-metric="assignment"] {
+    border-left-color: #74d6ad;
+}
+
+.tour-coverage-heading {
+    display: flex;
+    gap: 8px;
+    justify-content: space-between;
+    color: var(--tour-muted);
+    line-height: 1.35;
+}
+
+.tour-coverage-heading strong {
+    flex: none;
+    color: var(--tour-body);
+    font-weight: 600;
+}
+
+.tour-coverage-meter {
+    height: 3px;
+    overflow: hidden;
+    border-radius: 999px;
+    background: rgba(255, 255, 255, 0.1);
+}
+
+.tour-coverage-meter span {
+    display: block;
+    height: 100%;
+    border-radius: inherit;
+    background: var(--tour-accent-bright);
+}
+
+.tour-coverage-item[data-metric="assignment"] .tour-coverage-meter span {
+    background: #74d6ad;
+}
+
 .tour-search {
     padding: 10px 12px;
     border-bottom: 1px solid var(--tour-border);
@@ -775,6 +839,7 @@ body.tour-discussion .tour-narrative-resizer {
 }
 
 .tour-step[hidden],
+.tour-step-requirement[hidden],
 .tour-connection[hidden] {
     display: none;
 }
@@ -782,6 +847,42 @@ body.tour-discussion .tour-narrative-resizer {
 .tour-step-title { color: #fff; font-size: 13px; font-weight: 750; }
 .tour-step-body { margin: 3px 0 0; color: var(--tour-body); line-height: 1.45; }
 
+.tour-step-requirement {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: baseline;
+    gap: 6px;
+    margin-top: 4px;
+    color: var(--tour-muted);
+    line-height: 1.45;
+}
+
+.tour-requirement-chip {
+    padding: 1px 6px;
+    border: 1px solid rgba(166, 140, 255, 0.34);
+    border-radius: 9px;
+    color: var(--tour-body);
+    font-size: 12px;
+    font-weight: 700;
+    white-space: nowrap;
+}
+
+.tour-requirement-chip[data-status="fulfilled"] {
+    border-color: rgba(122, 214, 160, 0.42);
+    background: rgba(122, 214, 160, 0.1);
+}
+
+.tour-requirement-chip[data-status="gap"] {
+    border-color: rgba(240, 168, 120, 0.46);
+    background: rgba(240, 168, 120, 0.12);
+}
+
+.tour-requirement-meta {
+    flex-basis: 100%;
+    color: var(--tour-faint);
+    font-size: 12px;
+}
+
 .tour-connection {
     margin-top: 7px;
     padding-top: 7px;