@davmash/bygone 0.8.16 → 0.9.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davmash/bygone",
-  "version": "0.8.16",
+  "version": "0.9.2",
   "description": "See how change happened. Visual diff and file history.",
   "author": "David Mashburn",
   "license": "MIT",
@@ -40,7 +40,7 @@
     "electron"
   ],
   "dependencies": {
-    "electron": "^43.1.1",
+    "electron": "^43.7.6",
     "electron-updater": "^6.8.9",
     "js-yaml": "^4.3.0"
   }

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

@@ -7,7 +7,7 @@
   "additionalProperties": false,
   "required": ["version", "anchors", "connections", "chapters"],
   "properties": {
-    "version": { "enum": [1, 2] },
+    "version": { "enum": [1, 2, 3] },
     "title": { "$ref": "#/$defs/nonEmptyString" },
     "windowTitle": {
       "$ref": "#/$defs/nonEmptyString",
@@ -34,6 +34,7 @@
         }
       }
     },
+    "review": { "$ref": "#/$defs/review" },
     "anchors": {
       "type": "object",
       "propertyNames": { "minLength": 1 },
@@ -56,9 +57,35 @@
       "type": "array",
       "minItems": 1,
       "items": { "$ref": "#/$defs/chapter" }
+    },
+    "tours": {
+      "type": "object",
+      "additionalProperties": false,
+      "minProperties": 1,
+      "properties": {
+        "historical": { "$ref": "#/$defs/historicalTour" },
+        "deconstructed": { "$ref": "#/$defs/deconstructedTour" }
+      }
     }
   },
   "allOf": [
+    {
+      "if": { "properties": { "version": { "enum": [1, 2] } }, "required": ["version"] },
+      "then": {
+        "not": { "anyOf": [{ "required": ["tours"] }, { "required": ["review"] }] },
+        "properties": {
+          "chapters": {
+            "items": {
+              "properties": {
+                "scenes": {
+                  "items": { "not": { "required": ["overview"] } }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     {
       "if": { "properties": { "version": { "const": 1 } }, "required": ["version"] },
       "then": {
@@ -79,7 +106,7 @@
       }
     },
     {
-      "if": { "properties": { "version": { "const": 2 } }, "required": ["version"] },
+      "if": { "properties": { "version": { "enum": [2, 3] } }, "required": ["version"] },
       "then": {
         "properties": {
           "chapters": {
@@ -100,6 +127,7 @@
   ],
   "$defs": {
     "nonEmptyString": { "type": "string", "minLength": 1 },
+    "reviewString": { "type": "string", "minLength": 1, "pattern": "\\S" },
     "stringArray": {
       "type": "array",
       "items": { "type": "string" }
@@ -146,6 +174,28 @@
         "takeaway": { "$ref": "#/$defs/nonEmptyString" }
       }
     },
+    "sceneOverview": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind"],
+      "properties": {
+        "kind": { "const": "directory-diff" },
+        "comparison": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["from", "to"],
+          "properties": {
+            "from": { "$ref": "#/$defs/nonEmptyString" },
+            "to": { "$ref": "#/$defs/nonEmptyString" }
+          }
+        },
+        "path": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^(?!/)(?![A-Za-z]:)(?!.*\\\\)(?!.*(?:^|/)\\.\\.(?:/|$)).*$"
+        }
+      }
+    },
     "requirement": {
       "type": "object",
       "additionalProperties": false,
@@ -158,6 +208,63 @@
         "confidence": { "enum": ["high", "medium", "low"] }
       }
     },
+    "review": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["baseOid", "headOid", "items"],
+      "properties": {
+        "baseOid": { "$ref": "#/$defs/fullGitOid" },
+        "headOid": { "$ref": "#/$defs/fullGitOid" },
+        "items": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/reviewItem" }
+        }
+      }
+    },
+    "fullGitOid": {
+      "type": "string",
+      "pattern": "^(?:[0-9a-fA-F]{40}|[0-9a-fA-F]{64})$"
+    },
+    "reviewItem": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "kind", "title", "body", "evidence"],
+      "properties": {
+        "id": { "$ref": "#/$defs/reviewString" },
+        "kind": { "enum": ["concept", "boundary", "tradeoff", "question"] },
+        "title": { "$ref": "#/$defs/reviewString" },
+        "body": { "$ref": "#/$defs/reviewString" },
+        "evidence": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/reviewEvidence" }
+        },
+        "nextCheck": { "$ref": "#/$defs/reviewString" }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": { "kind": { "const": "question" } },
+            "required": ["kind"]
+          },
+          "then": { "required": ["nextCheck"] },
+          "else": {
+            "properties": {
+              "evidence": { "minItems": 1 }
+            }
+          }
+        }
+      ]
+    },
+    "reviewEvidence": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["sceneId", "stepId"],
+      "properties": {
+        "sceneId": { "$ref": "#/$defs/reviewString" },
+        "stepId": { "$ref": "#/$defs/reviewString" }
+      }
+    },
     "step": {
       "type": "object",
       "additionalProperties": false,
@@ -191,11 +298,13 @@
           "required": ["id", "title", "summary", "bullets", "tags", "takeaway", "steps"],
           "properties": {
             "id": { "$ref": "#/$defs/nonEmptyString" },
+            "kind": { "const": "walkthrough" },
             "title": { "$ref": "#/$defs/nonEmptyString" },
             "summary": { "$ref": "#/$defs/nonEmptyString" },
             "bullets": { "$ref": "#/$defs/stringArray" },
             "tags": { "$ref": "#/$defs/stringArray" },
             "takeaway": { "$ref": "#/$defs/nonEmptyString" },
+            "overview": { "allOf": [{ "$ref": "#/$defs/sceneOverview" }, { "not": { "required": ["comparison"] } }] },
             "steps": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/step" } }
           }
         }
@@ -247,6 +356,7 @@
         "bullets": { "$ref": "#/$defs/stringArray" },
         "tags": { "$ref": "#/$defs/stringArray" },
         "takeaway": { "$ref": "#/$defs/nonEmptyString" },
+        "overview": { "$ref": "#/$defs/sceneOverview" },
         "stack": { "type": "array", "minItems": 2, "maxItems": 6, "items": { "$ref": "#/$defs/stackEntry" } },
         "files": { "$ref": "#/$defs/stringArray" },
         "steps": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/stackStep" } }
@@ -306,6 +416,7 @@
         "bullets": { "$ref": "#/$defs/stringArray" },
         "tags": { "$ref": "#/$defs/stringArray" },
         "takeaway": { "$ref": "#/$defs/nonEmptyString" },
+        "overview": { "$ref": "#/$defs/sceneOverview" },
         "base": { "$ref": "#/$defs/nonEmptyString" },
         "target": { "$ref": "#/$defs/nonEmptyString" },
         "stack": { "type": "array", "minItems": 2, "maxItems": 6, "items": { "$ref": "#/$defs/stackEntry" } },
@@ -341,6 +452,59 @@
           }
         }
       }
+    },
+    "historicalTour": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["chapters"],
+      "properties": {
+        "chapters": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/historicalChapter" }
+        }
+      }
+    },
+    "historicalChapter": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "title", "scenes"],
+      "properties": {
+        "id": { "$ref": "#/$defs/nonEmptyString" },
+        "title": { "$ref": "#/$defs/nonEmptyString" },
+        "scenes": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "oneOf": [
+              { "$ref": "#/$defs/scene" },
+              { "$ref": "#/$defs/stackedScene" }
+            ]
+          }
+        }
+      }
+    },
+    "deconstructedTour": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["chapters"],
+      "properties": {
+        "chapters": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/chapter" },
+          "contains": {
+            "type": "object",
+            "required": ["scenes"],
+            "properties": {
+              "scenes": {
+                "type": "array",
+                "contains": { "$ref": "#/$defs/deconstructedScene" }
+              }
+            }
+          }
+        }
+      }
     }
   }
 }

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

@@ -98,6 +98,10 @@ Do not rebuild, commit, push, publish, or open a browser unless the user request
 
 Determine the intended head and base from the request and repository state. Prefer an explicit base; do not guess when different bases would materially change the explanation.
 
+Treat workspace paths named by the request as the explicit scope. The context
+does not provide a path filter, so do not silently narrow or broaden that scope
+based on which files seem easiest to explain; surface any scope ambiguity.
+
 For a hosted review, resolve both immutable endpoint OIDs from provider metadata. Never assume the current checkout is the requested review head. For GitHub:
 
 ```sh
@@ -109,9 +113,16 @@ test -n "$HEAD_OID" && test "$HEAD_OID" != null
 bygone tour context "$HEAD_OID" --base "$BASE_OID" --output /tmp/change-context.json
 ```
 
-Use the equivalent API or CLI fields for other providers. If you are not reviewing a hosted change, compute the merge-base against the intended integration branch and pass that exact base OID or ref. Keep the existing preference for explicit endpoints and do not guess.
+Use the equivalent API or CLI fields for other providers. If the requested
+endpoints are unresolved, reversed, divergent, or have multiple candidates,
+stop and report the ambiguity. Never silently invent an endpoint, choose among
+candidates, or substitute a merge-base. If you are not reviewing a hosted
+change, compute the merge-base only when the intended integration branch is
+explicit, and pass that exact base OID or ref.
 
-Use immutable commit IDs in the eventual tour. Dirty working-tree changes are reported but excluded from committed-range context.
+Use immutable commit IDs in the eventual tour. Dirty working-tree changes and
+unsaved buffers are reported separately but excluded from committed-range
+context, authored evidence, and compiled source.
 
 Inspect progressively instead of loading every patch immediately:
 
@@ -164,19 +175,52 @@ Retrieve the current contract:
 bygone tour schema > /tmp/change-tour-source.schema.json
 ```
 
-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.
+Write a version 3 `.bygone` file for new tours. 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. Versions 1 and 2 remain readable for legacy
+inputs; v3 is the format for independent authored modes, directory overviews,
+and review notes.
 
 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
 stay distinguishable. When omitted, the presenter falls back to `title`.
 
-For every step:
+### Choose the authored modes
+
+The root `chapters` is required and is the compatibility tour. It shares the
+top-level `range`, `anchors`, and `connections` with any independent modes.
+When the source supplies them, `tours.historical.chapters` and
+`tours.deconstructed.chapters` are separate authored tours; keep their chapter,
+scene, and step order independent rather than expecting Bygone to match content
+across modes.
+
+- **Historical** explains real revision states. Its scenes may be walkthroughs
+  or `stacked-diff` scenes, never `deconstructed-diff` scenes. Every stacked
+  panel must resolve to a real Git revision; an explicitly authored Historical
+  stack may contain two to six revisions, but its first and last panels must be
+  the resolved review base and head.
+- **Deconstructed** explains the change through synthetic cumulative stages. It
+  must contain at least one `deconstructed-diff` scene and may include
+  walkthrough scenes for context or proof. A mode-specific deconstructed scene
+  may omit `stack` and endpoint `steps`: its stages, not Git history, define the
+  explanation panels.
+- If a mode is omitted, v3 derives it from the root chapters by scene identity
+  and order. Root walkthroughs and real stacks supply Historical; root
+  deconstructed scenes supply Deconstructed. A root deconstructed scene enters
+  Historical only when it also has explicit endpoint walkthrough `steps`; a
+  real revision `stack` by itself is not that walkthrough. No cross-mode
+  correspondence is inferred from filenames or narrative text.
+
+For a root v3 `deconstructed-diff` scene, provide both an explicit real
+revision `stack` and regular endpoint `steps`. The stack is used for the real
+Historical/Final fallback and must have the same base and final endpoints as
+the source range; the synthetic stages remain separate. A
+mode-specific Deconstructed scene may omit those fields as described above.
+
+For every walkthrough step:
 
 - make one concise explanatory claim;
 - focus an anchor in `base` or `head` evidence;
@@ -185,13 +229,49 @@ 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.
 
+For every `stacked-diff` step, use a real changed file and a `pair` of adjacent
+stack entry IDs; use `side` or `lines` only to refine the focus. For every
+deconstructed stage, assign concrete change-unit (hunk) IDs through `changes`
+and build a cumulative teaching order. Assign each changed hunk exactly once,
+or exclude it explicitly with a reason; unsupported, binary, and rename-path
+changes generally need whole-file exclusions. Do not infer a real stack from
+the synthetic stages or describe an explanation panel as a commit.
+
 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.
+- A **stage** is an authored synthetic phase and cumulative comparison state;
+  it is not a Git revision.
+- The presenter derives one or more navigable Deconstructed tour steps from a
+  stage's introduced changes. A root deconstructed scene's endpoint `steps`
+  are ordinary anchor-based walkthrough items for the real range, not those
+  synthetic stage steps.
 - 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.
 
+Version 3 scenes may include a directory Overview:
+
+```yaml
+overview:
+  kind: directory-diff
+  path: web
+```
+
+Keep `path` relative and POSIX-style; omit it or use `.` for the repository
+root. Stacked and Deconstructed scenes may set `overview.comparison` to two
+distinct stack-entry IDs or to `explanation-baseline` and
+`explanation-stage-<stage-id>`. Walkthrough overviews always use the review's
+base-to-head comparison and reject an explicit comparison.
+
+Use the optional v3 top-level `review` block for evidence-linked concepts,
+boundaries, tradeoffs, and unresolved questions instead of presenting open
+questions as settled scene narration. Pin `review.baseOid` and `review.headOid`
+to the resolved range. `concept`, `boundary`, and `tradeoff` items need at
+least one link to a root authored walkthrough scene and step; a `question` may
+have empty evidence but must provide `nextCheck`. Do not add an ad hoc `notes`
+key. See `examples/bygone-history.bygone` for review notes and
+`examples/navigation-lab.bygone.yaml` for independently authored v3 modes.
+
 Never emit generated line numbers or hunk indexes. Verify candidate snippets against the pinned object when uncertain:
 
 ```sh
@@ -220,7 +300,16 @@ 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;
+- every Historical tour excludes synthetic deconstructed scenes, and every
+  Deconstructed tour contains at least one deconstructed scene;
+- deconstructed stages cover every included change unit exactly once or record
+  an explicit exclusion, contain no unqualified "Stage N" or "Step N"
+  references, and keep comparison stages distinct from navigable tour steps;
+- root deconstructed scenes have the required real stack and endpoint
+  walkthrough evidence, while mode-specific synthetic scenes do not claim
+  that evidence exists;
+- v3 review-note OIDs match the resolved range and evidence links resolve to
+  authored root walkthrough steps;
 - the final step supplies proof or a clear reviewer conclusion.
 
 ## Always print the open command
@@ -268,7 +357,9 @@ Report:
 - the exact base and head OIDs;
 - the **open command** for the primary artifact (`bygone present --tour …`, `bygone review …`, `bygone --git-diff …`, etc.);
 - the source and compiled artifact paths;
-- authored chapter, scene, and step counts, plus compiled counts when the generated complete-change appendix changes them;
+- authored root and Historical/Deconstructed chapter, scene, step, and stage
+  counts, plus compiled counts when generated complete-change or per-mode
+  scenes change them;
 - omitted or unread evidence;
 - validation and visual verification performed;
 - whether generated files are temporary, uncommitted, committed, or pushed.

package/standalone/index.html

@@ -3,7 +3,7 @@
 <head>
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <meta http-equiv="Content-Security-Policy" content="default-src 'self'; base-uri 'none'; object-src 'none'; frame-src 'none'; form-action 'none'; img-src 'self' data:; font-src 'self' data:; style-src 'self' 'unsafe-inline'; script-src 'self'; worker-src 'self' blob:;">
+    <meta http-equiv="Content-Security-Policy" content="default-src 'self'; base-uri 'none'; object-src 'none'; frame-src http://127.0.0.1:*; form-action 'none'; img-src 'self' data:; font-src 'self' data:; style-src 'self' 'unsafe-inline'; script-src 'self'; worker-src 'self' blob:;">
     <title>Bygone</title>
     <link href="../media/webview.css" rel="stylesheet">
 </head>