@opengsd/gsd-path 1.4.0 → 1.5.0

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

@@ -84,6 +84,17 @@ settled brownfield input.
    template before dispatch. Record every standard dimension exactly once as
    `dispatched` or `skipped` with a reason, and assign every research question
    to at least one dispatched dimension. No question may remain unassigned.
+   Copy each question to exactly one `Question assignments` row. Assign one or
+   more dispatched dimension slugs there, each in its own code span and
+   separated by commas, as in:
+
+   ```md
+   - `[RESEARCH] Which approach is viable?` → `stack`, `pitfalls`
+   ```
+
+   List a dimension only once per row. Every dispatched dimension must own at
+   least one question, and its evidence file must answer every question
+   assigned to it. Use `- none` only when there are no research questions.
 2. Decide which standard dimensions have work: dispatch a dimension only when
    it has at least one assigned `RESEARCH` question from INTENT.md or
    CHARTER.md. Unsettled choices and risks need that source question before

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

@@ -44,6 +44,19 @@ use exactly one matching branch:
   create another worktree. Encode task dependencies explicitly; launch
   independent children concurrently up to the host's advertised
   concurrent-subagent capacity.
+- A `muse.subagent_spawn` tool (with `muse.subagent_wait`,
+  `muse.subagent_read_result`, and `muse.subagent_send_message` siblings) is
+  Muse Code. Omit `subagent_type` (general-purpose, full capability), pass the
+  logical task name as `task_name` and `role`, and the complete brief as
+  `objective`. Never set `worktree_isolation`. Keep the returned
+  `subagent_id`; send a correction to a still-live child with
+  `muse.subagent_send_message` mode `followup` and the complete new prompt,
+  otherwise start a fresh child. Collect with `muse.subagent_wait`
+  (`wait_for: task_terminal`) then `muse.subagent_read_result`; on
+  `root_capacity_exhausted`, wait for a child to finish and retry. Spawn has no
+  model or effort argument, so record no such capability. If only
+  `muse.workflow` is exposed (untrusted workspace), do not script or inline
+  the work; stop and report that the workspace must be trusted.
 
 For every branch:
 

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

@@ -65,6 +65,49 @@ VERIFY_RESULTS = ("pass", "fail")
 VERIFY_LEDGER_SCHEMA = "gsd-path/verify-ledger/v2"
 VERIFY_BLOCK_PATTERN = re.compile(r"```bash[ \t]*\n(?P<block>.*?)```", re.DOTALL)
 
+REVIEW_BULLET_HEADING_PATTERN = re.compile(r"^#{2,3} ")
+REVIEW_BULLET_FIELD_LABEL_PATTERN = re.compile(r"^- \*\*[^*]+\*\*:")
+
+
+def review_bullet_field_label_pattern(field: str) -> re.Pattern[str]:
+    return re.compile(rf"^- \*\*{re.escape(field)}\*\*:[ \t]*(.*)$")
+
+
+def _review_bullet_field_value(lines: Sequence[str], index: int, inline: str) -> str:
+    if inline:
+        return inline
+    collected: list[str] = []
+    for line in lines[index + 1 :]:
+        if REVIEW_BULLET_FIELD_LABEL_PATTERN.match(line) or REVIEW_BULLET_HEADING_PATTERN.match(
+            line
+        ):
+            break
+        if line and not line[0].isspace():
+            break
+        stripped = line.strip()
+        if stripped:
+            collected.append(stripped)
+    return "\n".join(collected)
+
+
+def find_review_bullet_field_values(lines: Sequence[str], field: str) -> list[str]:
+    pattern = review_bullet_field_label_pattern(field)
+    values: list[str] = []
+    for index, line in enumerate(lines):
+        match = pattern.fullmatch(line)
+        if match is None:
+            continue
+        values.append(_review_bullet_field_value(lines, index, match.group(1)))
+    return values
+
+
+def parse_review_bullet_field(lines: Sequence[str], field: str) -> str:
+    """Parse one `- **Field**:` review bullet, including indented continuations."""
+    values = find_review_bullet_field_values(lines, field)
+    if len(values) != 1:
+        raise ValueError(field)
+    return values[0]
+
 
 # Sample paths the pipeline must commit. A product rule such as an unanchored
 # `build/` would otherwise drop them silently from every commit.
@@ -150,6 +193,11 @@ def verify_ledger_entries(path: Path) -> list:
     return parse_verify_ledger(path.read_text(encoding="utf-8"))
 
 
+def read_user_text(path: Path) -> str:
+    """Read a user-edited text file with CRLF normalized to LF."""
+    return path.read_text(encoding="utf-8").replace("\r\n", "\n").replace("\r", "\n")
+
+
 def parse_verify_ledger(text: str) -> list:
     entries = []
     for number, line in enumerate(text.splitlines(), start=1):
@@ -204,7 +252,43 @@ def run_command(
 def run_git(
     repo: Path, *arguments: str, input: Optional[str] = None
 ) -> subprocess.CompletedProcess[str]:
-    return _run_exact(("git", "-C", str(repo), *arguments), input=input)
+    return _run_exact(git_command(repo, *arguments), input=input)
+
+
+def git_command(repo: Path, *arguments: str) -> tuple[str, ...]:
+    """Git argv for repo, including WSL drvfs workarounds when needed."""
+    return ("git", "-C", str(repo), *git_drvfs_config_flags(repo), *arguments)
+
+
+def git_drvfs_config_flags(repo: Path) -> tuple[str, ...]:
+    """Disable index preload on 9p/drvfs mounts where git commit races on index.lock (#207)."""
+    if os.name != "posix":
+        return ()
+    try:
+        root = repo.resolve()
+        mounts = Path("/proc/mounts").read_text(encoding="utf-8", errors="replace").splitlines()
+    except OSError:
+        return ()
+    best = ""
+    fstype = ""
+    for line in mounts:
+        parts = line.split()
+        if len(parts) < 3:
+            continue
+        mount_point, mount_type = parts[1], parts[2]
+        if mount_type not in {"9p", "drvfs"}:
+            continue
+        if root == Path(mount_point) or root.is_relative_to(mount_point):
+            if len(mount_point) >= len(best):
+                best, fstype = mount_point, mount_type
+    if not fstype:
+        return ()
+    return ("-c", "core.preloadindex=false", "-c", "index.threads=1")
+
+
+def git_index_lock_retryable(stderr: str) -> bool:
+    text = stderr.casefold()
+    return "index.lock" in text and "file exists" in text
 
 
 # OS files that are never pipeline artifacts when git ignores them.
@@ -227,6 +311,70 @@ def git_visible_entries(directory: Path) -> set:
     return {path.split("/", 1)[0] for path in result.stdout.split("\0") if path}
 
 
+RUNTIME_PIN_PATH = ".gsd-path/runtime.json"
+RUNTIME_PIN_ALLOWANCE = (
+    "only runtime-pin commits (.gsd-path/runtime.json) may follow the reviewed HEAD"
+)
+
+
+def reviewed_head_covers(repo: Path, reviewed: str, head: str) -> bool:
+    """True when a review of `reviewed` still covers `head`.
+
+    That is the same commit, or `reviewed` is an ancestor of `head` and every
+    commit on the first-parent path in ``reviewed..head`` is a non-merge commit
+    whose only change is ``.gsd-path/runtime.json``. An empty commit does not
+    qualify. Any other path, any merge commit, an unresolvable SHA, or a
+    non-ancestor returns False.
+    """
+    if not reviewed or not head:
+        return False
+    resolved_repo = Path(repo)
+    resolved: List[str] = []
+    for value in (reviewed, head):
+        result = run_git(
+            resolved_repo, "rev-parse", "--verify", "--quiet", f"{value}^{{commit}}"
+        )
+        if result.returncode != 0 or not result.stdout.strip():
+            return False
+        resolved.append(result.stdout.strip())
+    reviewed_sha, head_sha = resolved
+    if reviewed_sha == head_sha:
+        return True
+    if (
+        run_git(resolved_repo, "merge-base", "--is-ancestor", reviewed_sha, head_sha).returncode
+        != 0
+    ):
+        return False
+    listing = run_git(
+        resolved_repo,
+        "rev-list",
+        "--first-parent",
+        "--parents",
+        f"{reviewed_sha}..{head_sha}",
+    )
+    if listing.returncode != 0:
+        return False
+    for line in listing.stdout.splitlines():
+        fields = line.split()
+        if len(fields) != 2:
+            return False
+        commit_sha, parent_sha = fields[0], fields[1]
+        changed = run_git(
+            resolved_repo,
+            "diff",
+            "--name-only",
+            "--no-renames",
+            "--no-ext-diff",
+            parent_sha,
+            commit_sha,
+        )
+        if changed.returncode != 0:
+            return False
+        if {path for path in changed.stdout.splitlines() if path} != {RUNTIME_PIN_PATH}:
+            return False
+    return True
+
+
 def atomic_replace(path: Path, temporary_path: Path, content: str) -> None:
     temporary_path.parent.mkdir(parents=True, exist_ok=True)
     descriptor = None

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

@@ -426,10 +426,10 @@ def frontmatter_value(content: str, key: str) -> Optional[str]:
     for line in lines[1:]:
         if line == "---":
             break
-        match = re.match(rf"^{re.escape(key)}:\s*([^#]*?)\s*(?:#.*)?$", line)
+        match = re.match(rf"^{re.escape(key)}:(.*)$", line)
         if match:
-            value = match.group(1).strip().strip('"').strip("'")
-            return value
+            value = _common.strip_yaml_comment(match.group(1))
+            return value.strip().strip('"').strip("'")
     return None
 
 
@@ -586,14 +586,11 @@ def resolved_archive_target(
     expected_number = milestone_number(branch)
     configured = parsed_state.archive
     entries = archive_sequence_entries(project)
-    missing_prior = [
-        number for number in range(1, expected_number) if number not in entries
-    ]
     later = sorted(number for number in entries if number > expected_number)
-    if missing_prior or later:
+    if later:
         raise ArchiveError(
             f"archive sequence does not match bound branch {branch}: "
-            f"missing={missing_prior}, later={later}"
+            f"later={later}"
         )
 
     if configured is not None:
@@ -1065,9 +1062,10 @@ def prepare_locked(project: Path, active_root: Path, slug: str) -> dict:
         final = active_root / "review" / "FINAL.md"
         reviewed = re.search(r"(?m)^Reviewed HEAD:\s*(\S+)", final.read_text(encoding="utf-8")) if final.is_file() else None
         head = require_git_success(run_git(project, "rev-parse", "HEAD"), "resolve HEAD").strip()
-        if reviewed and reviewed.group(1) != head:
+        if reviewed and not _common.reviewed_head_covers(project, reviewed.group(1), head):
             raise ArchiveError(
                 f"FINAL.md Reviewed HEAD {reviewed.group(1)} does not match current HEAD {head}; "
+                f"{_common.RUNTIME_PIN_ALLOWANCE}; "
                 "re-run the final review on the current commit before archiving"
             )
         target = resolved_archive_target(project, slug, parsed_state)
@@ -1680,6 +1678,7 @@ def abandon_locked(
 
 
 run_git = _common.run_git
+reviewed_head_covers = _common.reviewed_head_covers
 run_command = _common.run_command
 
 
@@ -1899,9 +1898,10 @@ def preflight(repo: Path) -> dict:
     require_stageable_carry_forward(project, archive)
     require_clean_older_archives(project, configured)
     head = require_git_success(run_git(project, "rev-parse", "HEAD"), "resolve preflight HEAD")
-    if reviewed_head != head:
+    if not reviewed_head_covers(project, reviewed_head, head):
         raise ArchiveError(
-            f"FINAL.md Reviewed HEAD {reviewed_head} does not match current HEAD {head}"
+            f"FINAL.md Reviewed HEAD {reviewed_head} does not match current HEAD {head}; "
+            f"{_common.RUNTIME_PIN_ALLOWANCE}"
         )
     return {
         "archive": configured,
@@ -2093,9 +2093,10 @@ def validate(repo: Path, *, historical: bool = False) -> dict:
 
     members = member_ship_rows(project, archive, ship_commit)
     ship_parent = require_git_success(run_git(project, "rev-parse", f"{ship_commit}^"), "resolve ship parent")
-    if reviewed_head != ship_parent:
+    if not reviewed_head_covers(project, reviewed_head, ship_parent):
         raise ArchiveError(
-            f"FINAL.md Reviewed HEAD {reviewed_head} does not match ship parent {ship_parent}"
+            f"FINAL.md Reviewed HEAD {reviewed_head} does not match ship parent {ship_parent}; "
+            f"{_common.RUNTIME_PIN_ALLOWANCE}"
         )
     require_canonical_commit_body(
         project,

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

@@ -1,5 +1,5 @@
 # gsd-path project runtime
-"""Guard a blocked build's return to Define or Plan using its committed base."""
+"""Guard return to Define or Plan using a committed recovery base."""
 
 from __future__ import annotations
 
@@ -17,7 +17,9 @@ EVENTS = {
     "define": "build intent corrections requested",
     "plan": "build plan repair requested",
 }
+PLAN_INTENT_EVENT = "plan intent corrections requested"
 MARKER = "build recovery: "
+RECOVERY_KEYS = frozenset({"base", "branch", "kind", "source"})
 
 
 def runtime():
@@ -36,9 +38,42 @@ def checkpoint_runtime():
     return state_checkpoint
 
 
+def _parse_recovery_record(value: object) -> dict:
+    if (
+        not isinstance(value, dict)
+        or not {"base", "branch", "kind"}.issubset(value)
+        or not set(value).issubset(RECOVERY_KEYS)
+        or not isinstance(value["base"], str)
+        or not re.fullmatch(r"[0-9a-f]{40}", value["base"])
+    ):
+        raise runtime().PipelineStateError("invalid build recovery record")
+    source = value.get("source", "build")
+    if source not in {"build", "plan"}:
+        raise runtime().PipelineStateError("invalid build recovery record")
+    if source == "plan":
+        if value["kind"] != "define":
+            raise runtime().PipelineStateError("invalid build recovery record")
+    elif value["kind"] not in EVENTS:
+        raise runtime().PipelineStateError("invalid build recovery record")
+    return {**value, "source": source}
+
+
+def _recovery_base_proves_milestone(before, current, source: str) -> bool:
+    if before.branch != current.branch or before.milestone != current.milestone:
+        return False
+    if source == "plan":
+        return (before.phase, before.status) in {("plan", "active"), ("plan", "blocked")}
+    return (before.phase, before.status) == ("build", "blocked")
+
+
 def context(repo: Path, text: str | None = None) -> dict | None:
     state = runtime()
-    current, loaded, _ = state.load_state(repo)
+    try:
+        current, loaded, _ = state.load_state(repo)
+    except state.PipelineStateError as error:
+        if "STATE.md must be a real file" not in str(error):
+            raise
+        return None
     text = loaded if text is None else text
     recovery = None
     for line in text.splitlines():
@@ -47,26 +82,24 @@ def context(repo: Path, text: str | None = None) -> dict | None:
         event = line.split(" — ", 2)[-1]
         if event.startswith(MARKER):
             try:
-                value = json.loads(event[len(MARKER):])
+                value = _parse_recovery_record(json.loads(event[len(MARKER):]))
             except ValueError as error:
                 raise state.PipelineStateError("invalid build recovery record") from error
-            if (not isinstance(value, dict) or set(value) != {"base", "branch", "kind"}
-                    or value["kind"] not in EVENTS
-                    or not isinstance(value["base"], str)
-                    or not re.fullmatch(r"[0-9a-f]{40}", value["base"])):
-                raise state.PipelineStateError("invalid build recovery record")
             recovery = {**value, "active": True} if value["branch"] == current.branch else None
-        elif event == "build started" and recovery:
-            recovery["active"] = False
+        elif recovery and recovery.get("active"):
+            source = recovery.get("source", "build")
+            if source == "build" and event == "build started":
+                recovery["active"] = False
+            elif source == "plan" and event == "plan approved":
+                recovery["active"] = False
     if recovery:
         if not state._is_ancestor(repo, recovery["base"], "HEAD"):
             raise state.PipelineStateError("build recovery base is not an ancestor of HEAD")
-        source = checkpoint_runtime()._git_text_at(repo, recovery["base"], ".project/STATE.md")
-        if source is None:
+        base_text = checkpoint_runtime()._git_text_at(repo, recovery["base"], ".project/STATE.md")
+        if base_text is None:
             raise state.PipelineStateError("build recovery base has no STATE.md")
-        before = state._state_from_text(source)
-        if ((before.phase, before.status) != ("build", "blocked")
-                or before.branch != current.branch or before.milestone != current.milestone):
+        before = state._state_from_text(base_text)
+        if not _recovery_base_proves_milestone(before, current, recovery.get("source", "build")):
             raise state.PipelineStateError("build recovery base does not prove this blocked milestone")
     return recovery
 
@@ -108,18 +141,20 @@ def settled_tasks(repo: Path) -> dict[str, tuple[str, dict]]:
     return tasks
 
 
-def begin(repo: Path, before, after, event: str) -> dict:
+def _begin_common(repo: Path, before, event: str) -> str:
     state = runtime()
-    if (before.phase, before.status) != ("build", "blocked") or after.phase not in EVENTS:
-        raise state.PipelineStateError("build recovery requires build/blocked")
-    if event != EVENTS[after.phase]:
-        raise state.PipelineStateError(f"state transition requires event: {EVENTS[after.phase]}")
     if before.archive is not None or before.branch != state._current_branch(repo):
         raise state.PipelineStateError("build recovery requires the active bound branch")
     if state._worktree_changes(repo):
         raise state.PipelineStateError("checkpoint the blocked build before recovery")
     if any(state.transaction_journals(repo).values()):
         raise state.PipelineStateError("finish pending transactions before build recovery")
+    state._read_real_file(repo / ".project/intent/INTENT.md", "INTENT.md")
+    return state._run_git(repo, "rev-parse", "HEAD").stdout.strip()
+
+
+def _settle_build_dispatch(repo: Path) -> None:
+    state = runtime()
     records = records_root(repo)
     for directory in {path.parent.parent for path in records.rglob("attempt-*/state.json")}:
         latest = max(directory.glob("attempt-*/state.json"), key=lambda path: int(path.parent.name.split("-")[1]))
@@ -128,19 +163,49 @@ def begin(repo: Path, before, after, event: str) -> dict:
                 or (record.get("worktree") and record.get("branch") and not record.get("cleanup_complete"))
                 or record.get("outcome") not in {"landed", "collected", "blocked", "resolved", "redispatched"}):
             raise state.PipelineStateError(f"settle dispatch records before recovery: {latest}")
-    tasks = settled_tasks(repo)
-    state._read_real_file(repo / ".project/plan/PLAN.md", "PLAN.md")
-    state._read_real_file(repo / ".project/intent/INTENT.md", "INTENT.md")
-    base = state._run_git(repo, "rev-parse", "HEAD").stdout.strip()
+
+
+def _verify_done_tasks(repo: Path, tasks: dict[str, tuple[str, dict]], base: str) -> None:
+    state = runtime()
     done = [repo / ".project/tasks" / name for name, (_, fields) in tasks.items()
             if fields["status"] == "done"]
-    if done:
-        if __package__:
-            from scripts.isolation import verify_landed_task_files
-        else:
-            from isolation import verify_landed_task_files
-        verify_landed_task_files(repo, done, ".project/tasks", base)
-    return {"kind": after.phase, "base": base, "branch": before.branch}
+    if not done:
+        return
+    if __package__:
+        from scripts.isolation import verify_landed_task_files
+    else:
+        from isolation import verify_landed_task_files
+    verify_landed_task_files(repo, done, ".project/tasks", base)
+
+
+def begin(repo: Path, before, after, event: str) -> dict:
+    state = runtime()
+    if (before.phase, before.status) == ("build", "blocked") and after.phase in EVENTS:
+        if event != EVENTS[after.phase]:
+            raise state.PipelineStateError(f"state transition requires event: {EVENTS[after.phase]}")
+        _settle_build_dispatch(repo)
+        tasks = settled_tasks(repo)
+        state._read_real_file(repo / ".project/plan/PLAN.md", "PLAN.md")
+        base = _begin_common(repo, before, event)
+        _verify_done_tasks(repo, tasks, base)
+        return {"kind": after.phase, "base": base, "branch": before.branch, "source": "build"}
+    if (
+        before.phase == "plan"
+        and before.status in {"active", "blocked"}
+        and (after.phase, after.status) == ("define", "active")
+    ):
+        if event != PLAN_INTENT_EVENT:
+            raise state.PipelineStateError(f"state transition requires event: {PLAN_INTENT_EVENT}")
+        state._read_real_file(repo / ".project/plan/PLAN.md", "PLAN.md")
+        tasks_dir = repo / ".project/tasks"
+        tasks = settled_tasks(repo) if tasks_dir.is_dir() and any(
+            path.is_file() and not state._common.is_ignored_junk(path)
+            for path in tasks_dir.iterdir()
+        ) else {}
+        base = _begin_common(repo, before, event)
+        _verify_done_tasks(repo, tasks, base)
+        return {"kind": "define", "base": base, "branch": before.branch, "source": "plan"}
+    raise state.PipelineStateError("build recovery requires build/blocked")
 
 
 def records_root(repo: Path) -> Path: