@opengsd/gsd-path 1.1.0 → 1.3.0

package/skills/gsd-path-plan/scripts/workflow_run.py

@@ -4,6 +4,7 @@
 import argparse
 import hashlib
 import json
+import os
 import subprocess
 import sys
 import tempfile
@@ -28,9 +29,10 @@ def run_workflow(repo: Path, action: str, project_dir: str, expected_head: str =
     steps = []
     outputs = {}
     scripts = Path(__file__).resolve().parent
+    helpers = scripts
 
     def step(script, *arguments, raw=False):
-        command = [sys.executable, "-B", str(scripts / script), *arguments]
+        command = [sys.executable, "-B", str(helpers / script), *arguments]
         completed = subprocess.run(command, cwd=repo, capture_output=True, text=True)
         receipt = {"script": script, "command": command, "exit_code": completed.returncode,
                    "stdout": completed.stdout, "stderr": completed.stderr}
@@ -49,6 +51,15 @@ def run_workflow(repo: Path, action: str, project_dir: str, expected_head: str =
 
     common = ["--repo", str(repo), "--project-dir", project_dir]
     try:
+        if os.path.lexists(repo / ".gsd-path/runtime.json"):
+            resolved = subprocess.run(
+                [sys.executable, "-B", str(repo / ".gsd-path/status_runtime.py"),
+                 "--repo", str(repo), "--runtime-path"],
+                cwd=repo, capture_output=True, text=True)
+            if resolved.returncode:
+                sys.stderr.write(resolved.stderr)
+                raise StepFailed(resolved.stderr.strip())
+            helpers = Path(resolved.stdout.strip())
         if action == "route":
             step("pipeline_state.py", "route", *common)
         elif action == "prepare-inspect":

package/skills/gsd-path-plan/scripts/worktree_paths.py

@@ -0,0 +1,94 @@
+#!/usr/bin/env python3
+# gsd-path project runtime
+"""Placement shared by task isolation, verification, and integration."""
+
+import sys
+
+# Runtime helpers must not modify their immutable installation.
+sys.dont_write_bytecode = True
+
+import hashlib
+import json
+import os
+import tempfile
+from pathlib import Path
+
+try:
+    import _common
+except ImportError:
+    from scripts import _common
+
+
+def _git(primary: Path, *args: str) -> str:
+    result = _common.run_git(primary, *args)
+    if result.returncode:
+        raise ValueError(result.stderr.strip() or "cannot inspect worktree placement")
+    return result.stdout.rstrip("\n")
+
+
+def _identity(path: Path) -> str:
+    return hashlib.sha256(os.fsencode(path)).hexdigest()
+
+
+def _workspace(primary: Path, pin: bool) -> Path:
+    common = Path(_git(primary, "rev-parse", "--git-common-dir"))
+    common = (primary / common).resolve()
+    identity = _identity(primary)
+    receipt = common / "gsd-path" / "workspaces" / f"{identity}.json"
+    try:
+        data = json.loads(receipt.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        pass
+    else:
+        if (not isinstance(data, dict) or data.get("primary") != str(primary)
+                or not isinstance(data.get("root"), str)
+                or not Path(data["root"]).is_absolute()):
+            raise ValueError(f"invalid worktree placement receipt: {receipt}")
+        return Path(data["root"])
+
+    root = Path(os.environ.get("GSD_PATH_WORKTREE_ROOT") or Path.home() / ".gsd-path" / "projects").expanduser()
+    if not root.is_absolute():
+        raise ValueError("GSD_PATH_WORKTREE_ROOT must be absolute")
+    root = root.resolve()
+    parent = root
+    while not parent.exists():
+        parent = parent.parent
+    ancestor = _common.run_git(parent, "rev-parse", "--git-common-dir")
+    same_repository = (
+        ancestor.returncode == 0
+        and (parent / ancestor.stdout.strip()).resolve() == common
+    )
+    if root.is_relative_to(primary) or same_repository:
+        raise ValueError(f"managed worktree root must be outside this repository's worktrees: {root}")
+    workspace = root / _identity(common) / identity
+    if pin:
+        receipt.parent.mkdir(parents=True, exist_ok=True)
+        fd, temporary = tempfile.mkstemp(dir=receipt.parent)
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as handle:
+                json.dump({"primary": str(primary), "root": str(workspace)}, handle)
+            try:
+                os.link(temporary, receipt)
+            except FileExistsError:
+                return _workspace(primary, False)
+        finally:
+            os.unlink(temporary)
+    return workspace
+
+
+def worktree_path(primary: Path, kind: str, name: str, *, pin: bool = False) -> Path:
+    primary = primary.resolve()
+    if kind not in {"task", "verify", "integrate"} or not name or Path(name).name != name or name in {".", ".."}:
+        raise ValueError("invalid managed worktree kind or name")
+    legacy = (primary.parent / f".{primary.name}-gsd-path-integrate-{name}"
+              if kind == "integrate" else primary.parent / f"{primary.name}.gsd-path" / kind / name)
+    branch = f"refs/heads/gsd-path-{kind}/{name}"
+    records = _git(primary, "worktree", "list", "--porcelain", "-z").split("\0\0")
+    for record in records:
+        fields = record.split("\0")
+        if f"worktree {legacy}" in fields and f"branch {branch}" in fields:
+            return legacy
+    # Keep collision checks and missing-directory recovery at the old location.
+    if os.path.lexists(legacy):
+        return legacy
+    return _workspace(primary, pin) / kind / name

package/skills/gsd-path-plan/templates/task.md

@@ -8,6 +8,8 @@ agent: null         # orchestrator-owned: set at dispatch
 base: null          # orchestrator-owned: clean layer SHA for isolated Verify
 worktree: null      # orchestrator-owned: isolated task worktree while active
 task_branch: null   # orchestrator-owned: gsd-path-task/<id> while parallel; null when serial
+# Optional explicit dispatch overrides: model: <advertised slug|inherit>
+# effort: <advertised effort|inherit>
 files:              # every file this task may touch — dispatch checks overlap
   - <path>
 ---

package/skills/gsd-path-research/SKILL.md

@@ -3,6 +3,8 @@ name: gsd-path-research
 description: Dispatch parallel researchers and collect cited GSD Path evidence about domain, stack, pitfalls, and comparable products. Use only when the user explicitly invokes $gsd-path-research or an active $gsd-path router explicitly routes to this phase.
 ---
 
+Before executing project helpers, read [runtime selection](references/runtime-selection.md).
+
 # GSD Path Research Phase
 
 Dispatch independent researchers and gate their evidence. Keep synthesis out

package/skills/gsd-path-research/references/dispatch.md

@@ -7,10 +7,7 @@ use exactly one matching branch:
 - A `spawn_agent` tool exposing `task_name`, `agent_type`, and `fork_turns` is
   Codex. Use `fork_turns: "none"`; coders use the built-in `worker` type and
   every other role uses `default`. Reuse a completed logical target with
-  `followup_task`. For Codex reasoning effort, use `high` for the portable
-  `heavy` tier and `low` for the portable `light` tier; leave reasoning effort
-  unset for the session-default tier, and never pass `heavy` or `light` as a
-  literal Codex value.
+  `followup_task`.
 - A `spawn_agent` tool without those Codex fields is Zed. Spawn one isolated,
   full-capability child per brief. Zed children are not resumable, so retries
   use a fresh child and a complete prompt.
@@ -26,7 +23,7 @@ use exactly one matching branch:
   the complete new prompt for later work. Wait for a colliding active child and
   collect results with `wait_commands_or_subagents`.
 - A `Task` tool advertising the custom `gsd-path` subagent is Cursor. Use that
-  model-inheriting, full-capability child. Resume it by returned agent ID when
+  full-capability child. Resume it by returned agent ID when
   available; otherwise retry with a fresh child and a complete prompt.
 - A `Task` tool advertising the built-in `general` subagent is OpenCode. Use
   that child; if an installed OpenCode v2 host exposes the renamed `subagent`
@@ -65,20 +62,10 @@ For every branch:
 - Resolve the phase's linked role brief to an absolute path, include it in the
   prompt, and require the child to read it before acting. The role brief
   supplies the read-only boundary for auditors and reviewers.
-- Tier hints: use the portable `heavy` tier for `plan`, `plan_patch`, `decide`,
-  and `roadmap`, the portable `light` tier for `inspect_docs` and `docs_audit`,
-  and the session-default tier for every other role. Apply the Codex mapping
-  above when its schema advertises reasoning-effort selection. On every other
-  host, use only an exact native equivalent advertised by that host; otherwise
-  do not override the model or reasoning effort. The only exception is a
-  review-panel child: when the host advertises model selection, pass the exact
-  slug returned by `scripts/review_panel.py resolve` for that family. Never
-  override the model on the canonical reviewer, planner, coder, or any other
-  role.
-  Host isolation: none. The child's working directory is the exact absolute
-  root GSD Path supplied; a host SHA checkout or extra worktree is a contract
-  failure. Never ask the host to create a worktree. Give the child the exact
-  repository or linked-worktree root supplied by GSD Path.
+- Model selection: before every child launch or continuation, follow
+  [the model-policy contract](model-policy.md) and apply its recorded
+  native arguments. It owns defaults, project settings, task overrides,
+  capability failures, and reassignment. Host isolation: none. Use the exact GSD Path supplied root; create no extra checkout.
 - Send a self-contained prompt with absolute input, template, and output paths
   plus the child's bounded responsibility. Every brief also names the absolute
   `AGENTS.md` and `WORKFLOW.md` paths (or explicitly says they are absent), the

package/skills/gsd-path-research/references/model-policy.md

@@ -0,0 +1,139 @@
+# Dispatch model policy
+
+Before native dispatch, run the bundled `scripts/model_policy.py`. CLI dispatch
+uses the same resolver inside `dispatch_driver.py`. The helper owns model and
+effort decisions; apply its output instead of choosing again in prose.
+
+## Project choices
+
+Use `<repo>/.project/model-policy.json`, including when the active track is
+`.project/next`. This file owns project overrides. It is not phase status.
+No file is required to retain existing behavior. `path config` can also set user
+defaults in `~/.gsd-path/config.json` under `models`. Project common roles override
+user host and common roles. Within each scope, host roles override common roles.
+Task overrides still win, and recorded assignments stay pinned.
+
+```json
+{
+  "roles": {"coder": {"model": "inherit"}},
+  "hosts": {"codex": {"plan": {"effort": "high"}}}
+}
+```
+
+Values are exact advertised model/effort strings or `inherit`. This example
+illustrates configuration; it is not a cost-saving preset. Set concrete models
+only from the current host's advertised choices. Host-specific role settings
+override common role settings. Task settings override both, independently for
+model and effort; omitted fields retain the next applicable value. Explicit
+`inherit` removes that field's override. There are no automatic fallbacks.
+
+Role keys are `coder`, `reviewer` (wave, final, and gap review), `review_panel`,
+`skeptic`, `inspect_codebase`, `inspect_docs`, `docs_audit`, `research`, `decide`,
+`roadmap`, `plan`, and `plan_patch`. Use the logical task name as the assignment,
+not as the role. Keep each panel family and review lens a distinct assignment.
+
+The helper retains heavy effort hints for plan, plan_patch, decide, and roadmap;
+light hints for inspect_docs and docs_audit; otherwise effort inherits. Codex
+maps these hints to high/low. Other hosts use only advertised equivalents.
+Hints are conditional; unsupported explicit settings stop the affected child.
+
+Coders may have scalar `model:` and `effort:` fields in their task frontmatter.
+These are part of the approved task contract. Pass the task file with `--task`.
+For other roles, pass assignment-specific `--model` or `--effort` when the owner
+explicitly overrides the role choice. Coder settings do not affect reviewers.
+
+## Advertised capabilities
+
+Capture the current child tool's schema and advertised choices in a JSON file
+outside the product tree. For each supported control, provide its native field,
+allowed values, and, for CLI dispatch, its documented argument template. Omit
+unsupported controls. The values below are fixture examples, not a host catalog:
+
+```json
+{
+  "host": "codex",
+  "model": {"field": "model", "values": ["example-model"],
+            "args": ["--model", "{value}"]},
+  "effort": {"field": "reasoning_effort", "values": ["low", "high"],
+             "args": ["-c", "model_reasoning_effort={value}"]}
+}
+```
+
+`effort_hints` may map heavy/light to exact advertised equivalents. Supply
+`inherited_model` only when the host exposes its identity. Never infer models,
+fields, or CLI flags from a host name. Every existing host uses this contract,
+including hosts with no model or effort controls. Their explicit unsupported
+settings block; their default inheritance remains usable.
+
+## Native lifecycle
+
+Resolve the bundled helper to an absolute path. Use one record under the Git
+common directory's `gsd-path/model-selection/` directory per assignment. Scope
+the path and `--scope` to the milestone, active/lookahead track, and review cycle
+where applicable; later work must not reuse an earlier record.
+
+```text
+python3 -B <helper> resolve --repo <primary> --scope <milestone/track/cycle> --assignment <logical-name> --role <role> --record <absolute-record> --capabilities <advertised-json>
+```
+
+Only `status: ready` authorizes launch. Apply `selection.native` exactly to
+the advertised child tool, preserving the host adapter's other controls and
+GSD Path task isolation. The recorded selection applies to a fresh child too.
+If an existing child is still active, reattach or send its continuation;
+resolving again does not authorize launching a second copy. When a host cannot
+change model/effort on a resumed child, a changed selection requires a fresh
+child after terminal completion of the earlier one.
+
+After terminal completion, release the assignment with `release` using the
+same identity arguments and `--terminal-result <host-completion-evidence>`.
+To change the selection, use `reassign` with the same identity, current
+capabilities, explicit model/effort changes, and `--ruling <verbatim-owner-ruling>`.
+It requires an inactive assignment and preserves prior selection history.
+Resolve again before starting the replacement. A project-policy edit alone
+does not change an existing selection. Task-contract edits still require their
+legal pipeline path.
+
+For panel children, first resolve membership with `review_panel.py resolve`,
+passing `--parent-slug` when known and repeating `--exclude-family` for every
+known parent and canonical-reviewer family (including all deep review lenses).
+Apply these exclusions before persisting membership. Detected membership skips
+excluded families; explicitly named conflicts block. Pass its selected model through `--panel-model`, and pass `--panel-family` plus
+`--exclude-family` for known parent and
+canonical-reviewer families. Persist and reuse the panel roster. Policy cannot
+waive family independence or change canonical review authority. A changed
+panel roster requires a new legal review assignment.
+
+Requested controls are durable evidence. When the host hides the inherited
+model identity, exact effective-model continuity across fresh children remains
+unproven; report that limitation rather than asserting an identity.
+
+## CLI lifecycle
+
+Pass `--model-capabilities <advertised-json>` to the driver. Commands use whole
+argument slots `{model_args}` and `{effort_args}`; the resolver expands these
+to argument arrays. They are not shell substitutions. Remove fixed model and
+effort flags when using these slots; conflicting controls block dispatch.
+Commands with explicit policy choices must expose the corresponding slots,
+including when an explicit choice is `inherit`. Unconfigured legacy commands
+without a capability file retain their existing behavior.
+An existing legacy assignment with no recorded selection keeps its saved
+command across retries, even if project policy or capabilities are later added.
+It cannot use `reassign-model`; model controls require a new explicit assignment.
+
+Review and skeptic commands accept `--model` and `--effort` for that assignment.
+For distinct panel families or review lenses, pass `--model-overrides <json>`:
+a mapping from exact logical assignment names to model/effort objects. Each
+entry applies only to its named assignment; conflicting explicit inputs block.
+A common panel model must satisfy every selected family, so use these scoped
+overrides when families need different models. Family checks remain mandatory.
+Coders read their task overrides. Panels with capabilities use the argument
+slots; legacy panel commands may retain their existing `{model}` placeholder.
+
+The driver persists selection before launch and retains it on retry. Use
+`dispatch_driver.py reassign-model --repo <primary> --task-id <logical-name>
+--model-capabilities <advertised-json> --model <slug> --ruling <owner-ruling>`
+for an inactive unfinished assignment. Finished work and pinned panel rosters
+require a new legal assignment. Earlier attempt evidence is retained.
+
+Compare total cost only with observed usage and outcomes, including retries.
+These controls do not establish cost savings, pricing, or quality rankings.

package/skills/gsd-path-research/references/runtime-selection.md

@@ -0,0 +1,25 @@
+# Project runtime selection
+
+Before running a project runtime helper, check for
+`<absolute-project>/.gsd-path/runtime.json`. When present, run the stable launcher:
+
+```sh
+python3 -B <absolute-project>/.gsd-path/status_runtime.py --repo <absolute-project> --runtime-path
+```
+
+Use `python` only when it is the compatible Python 3.9+ interpreter. A failure
+stops helper execution: follow the exact-version restore action in the error.
+Do not install, upgrade, or fall back to the current plugin's runtime implicitly.
+
+The returned directory is the verified Project runtime. Resolve helper names
+present in its `manifest.json` from that directory, including status, state,
+isolation, integration, archive, recovery, build-state, final-verification, and guard helpers.
+The workflow runner resolves its subprocess helpers from this same directory;
+helper imports stay within the selected runtime. This rule overrides
+references to bundled copies of those helpers. Other skill helpers, templates,
+and role briefs remain in the installed skill bundle. Pass `-B` to Python helper
+invocations so execution does not create bytecode in the runtime store.
+
+With no declaration, retain the legacy helper lookup. An existing
+`.gsd-path/runtime/` requires the explicit `--runtime-migrate --project PATH`
+operation before adopting external storage; review the resulting Git diff.

package/skills/gsd-path-research/scripts/_common.py

@@ -9,6 +9,11 @@ consuming module keep working.
 
 from __future__ import annotations
 
+import sys
+
+# Runtime helpers must not modify their immutable installation.
+sys.dont_write_bytecode = True
+
 import json
 import os
 import re

package/skills/gsd-path-research/scripts/archive_milestone.py

@@ -16,6 +16,9 @@ import re
 import shutil
 import subprocess
 import sys
+
+# Runtime helpers must not modify their immutable installation.
+sys.dont_write_bytecode = True
 from contextlib import contextmanager
 from datetime import date
 from pathlib import Path, PurePosixPath
@@ -1743,6 +1746,12 @@ def require_clean_active_root(active_root: Path, archive: Path) -> None:
     carried_forward = pending_ruling_count(archived_audit)
     # Persistent project metadata ships but never archives with a milestone.
     allowed = {"STATE.md", "REPOSITORY.md", "archive", "LESSONS.md", "next"}
+    for name in ("config.json", "model-policy.json"):
+        path = active_root / name
+        if path.exists() or path.is_symlink():
+            if path.is_symlink() or not path.is_file() or path.stat().st_nlink != 1:
+                raise ArchiveError(f"project settings must be a regular unlinked file: {path}")
+            allowed.add(name)
     if (active_root / "CHARTER.md").is_file():
         # Program flow: these persist at the .project/ top level.
         allowed |= {"CHARTER.md", "ROADMAP.md", "SYNTHESIS.md"}
@@ -1808,6 +1817,7 @@ def prepared_transaction(
     repo: Path,
     phases: Sequence[str],
     must_be_uncommitted: bool = False,
+    *, historical: bool = False,
 ) -> tuple:
     project = repo.resolve()
     active_root = require_project_layout(project)
@@ -1816,7 +1826,7 @@ def prepared_transaction(
     state, _, loaded_state_path = strict_state(project)
     if loaded_state_path.resolve() != state_path.resolve():
         raise ArchiveError("strict STATE.md loader returned an unexpected path")
-    require_transaction_context(project, state, phases)
+    require_transaction_context(project, state, phases, historical=historical)
 
     configured = state.archive
     if configured is None:
@@ -1880,10 +1890,11 @@ def require_canonical_commit_body(
         raise ArchiveError(f"{label} commit body does not match required fields")
 
 
-def find_ship_commit(project: Path, archive_name: str) -> str:
+def find_ship_commit(project: Path, archive_name: str, *, historical: bool = False) -> str:
     expected_subject = ship_subject(archive_name)
     log = require_git_success(
-        run_git(project, "log", "--first-parent", "--format=%H%x00%s", "HEAD"),
+        run_git(project, "log", *([] if historical else ["--first-parent"]),
+                "--format=%H%x00%s", "HEAD"),
         "inspect HEAD history for the ship commit",
     )
     matches = []
@@ -1926,19 +1937,22 @@ def validate_shipped_roadmap(text: str, state: PipelineState, archive: str) -> N
         raise ArchiveError("ROADMAP.md must record Status: shipped and the exact Archive")
 
 
-def validate(repo: Path) -> dict:
+def validate(repo: Path, *, historical: bool = False) -> dict:
     project, _, state, configured, archive, archived_files, reviewed_head = prepared_transaction(
         repo,
         ("shipped",),
+        historical=historical,
     )
     if state.status != "done":
         raise ArchiveError("STATE.md is not shipped/done")
 
-    project_status = require_git_success(run_git(project, "status", "--porcelain"), "inspect worktree status")
+    project_status = require_git_success(
+        run_git(project, "status", "--porcelain", *(["--", ".project"] if historical else [])),
+        "inspect worktree status")
     if project_status:
         raise ArchiveError("ship transaction worktree is not clean")
 
-    ship_commit = find_ship_commit(project, archive.name)
+    ship_commit = find_ship_commit(project, archive.name, historical=historical)
 
     parents = require_git_success(
         run_git(project, "rev-list", "--parents", "-n", "1", ship_commit),

package/skills/gsd-path-research/scripts/build_recovery.py

@@ -3,6 +3,11 @@
 
 from __future__ import annotations
 
+import sys
+
+# Runtime helpers must not modify their immutable installation.
+sys.dont_write_bytecode = True
+
 import json
 import re
 from pathlib import Path

package/skills/gsd-path-research/scripts/check_handoffs.py

@@ -7,6 +7,9 @@ import json
 import re
 import subprocess
 import sys
+
+# Runtime helpers must not modify their immutable installation.
+sys.dont_write_bytecode = True
 from pathlib import Path, PurePosixPath
 from typing import Dict, List, Optional, Sequence, Set, Tuple
 
@@ -131,6 +134,9 @@ def _strict_frontmatter(text: str, label: str) -> Dict[str, object]:
     while index < len(lines):
         line = lines[index]
         if line == "---":
+            for field in ('model', 'effort'):
+                if field in values and (not isinstance(values[field], str) or not values[field].strip()):
+                    raise HandoffError(f'{label}: {field} must be a nonempty scalar or inherit')
             return values
         if not line.strip() or line.lstrip().startswith("#"):
             index += 1

package/skills/gsd-path-research/scripts/check_task_briefs.py

@@ -6,6 +6,9 @@ import argparse
 import json
 import re
 import sys
+
+# Runtime helpers must not modify their immutable installation.
+sys.dont_write_bytecode = True
 from pathlib import Path, PurePosixPath
 from typing import Dict, List, Optional, Sequence, Set, Tuple
 

package/skills/gsd-path-research/scripts/detect_project.py

@@ -34,6 +34,9 @@ import re
 import stat
 import subprocess
 import sys
+
+# Runtime helpers must not modify their immutable installation.
+sys.dont_write_bytecode = True
 from datetime import date
 from pathlib import Path, PurePosixPath, PureWindowsPath
 from typing import Iterable, NamedTuple, Optional, Sequence
@@ -1200,7 +1203,14 @@ def filled_state_template(template: str, slug: str, phase: str) -> str:
     text = text.replace("YYYY-MM-DD — <phase> — project initialized", stamp)
     if "<slug>" in text or "YYYY-MM-DD" in text:
         raise DetectError("state template placeholder remains")
-    return text
+    try:
+        from .path_config import initial_state
+    except ImportError:
+        from path_config import initial_state
+    try:
+        return initial_state(text)
+    except (OSError, ValueError, RuntimeError) as error:
+        raise DetectError(str(error)) from error
 
 
 def write_all(descriptor: int, payload: bytes) -> None:

package/skills/gsd-path-research/scripts/discussion_records.py

@@ -7,6 +7,9 @@ import json
 import os
 import shutil
 import sys
+
+# Runtime helpers must not modify their immutable installation.
+sys.dont_write_bytecode = True
 from contextlib import contextmanager
 from datetime import date
 from pathlib import Path

package/skills/gsd-path-research/scripts/discussion_validate.py

@@ -2,6 +2,11 @@
 # gsd-path project runtime
 """Validate discussion records, reviews and the manifest for archive_milestone."""
 
+import sys
+
+# Runtime helpers must not modify their immutable installation.
+sys.dont_write_bytecode = True
+
 import json
 import re
 import shutil
@@ -409,7 +414,7 @@ def remove_interrupted_carry_copy(active_root: Path, archive: Path) -> None:
 
 
 def require_transaction_context(
-    project: Path, state: PipelineState, phases: Sequence[str]
+    project: Path, state: PipelineState, phases: Sequence[str], *, historical: bool = False
 ) -> None:
     phase = state.phase
     if phase not in phases:
@@ -429,7 +434,7 @@ def require_transaction_context(
     )
     if archive_milestone.is_unset(expected_branch):
         raise ArchiveError("STATE.md does not name a bound build branch")
-    if current_branch != expected_branch:
+    if current_branch != expected_branch and not historical:
         raise ArchiveError(
             f"current branch {current_branch!r} does not match STATE.branch {expected_branch!r}"
         )
@@ -446,7 +451,7 @@ def require_transaction_context(
         ),
         "inspect non-project worktree status",
     )
-    if non_project_status:
+    if non_project_status and not historical:
         raise ArchiveError("non-.project worktree changes block the archive transaction")