@opengsd/gsd-path 1.5.0 → 1.6.1

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

@@ -161,7 +161,8 @@ def _reject_placeholder(value: str, label: str) -> None:
     if placeholder is not None:
         raise HandoffError(
             f"{label} still contains the placeholder {placeholder.group(0)}; "
-            "replace it with the real value"
+            "replace it with the real value. A value cannot be only a placeholder; "
+            "literal text such as an HTML tag must be inside a sentence, in backticks"
         )
 
 
@@ -667,22 +668,30 @@ def _strip_comments(text: str) -> str:
     return COMMENT_PATTERN.sub("", text)
 
 
-def _numbered_items(section: str, *, continuations: bool = False) -> Dict[int, str]:
-    items: Dict[int, str] = {}
-    current = None
+def _numbered_entries(section: str, *, continuations: bool = False) -> List[Tuple[int, str]]:
+    """Each numbered item in document order; a repeated number stays a separate entry."""
+    entries: List[Tuple[int, str]] = []
+    open_item = False
     for line in _strip_comments(section).splitlines():
         match = NUMBERED_ITEM_PATTERN.fullmatch(line.strip())
         if not match:
-            if continuations and current is not None and line[:1].isspace() and line.strip():
-                items[current] += " " + line.strip()
+            if continuations and open_item and line[:1].isspace() and line.strip():
+                number, text = entries[-1]
+                entries[-1] = (number, text + " " + line.strip())
             elif line.strip():
-                current = None
+                open_item = False
             continue
-        number = int(match.group(1))
+        entries.append((int(match.group(1)), match.group(2).strip()))
+        open_item = True
+    return entries
+
+
+def _numbered_items(section: str, *, continuations: bool = False) -> Dict[int, str]:
+    items: Dict[int, str] = {}
+    for number, text in _numbered_entries(section, continuations=continuations):
         if number in items:
             raise HandoffError(f"repeated numbered item {number}")
-        items[number] = match.group(2).strip()
-        current = number
+        items[number] = text
     return items
 
 
@@ -693,7 +702,11 @@ def _success_criteria(intent: str) -> Dict[str, str]:
     expected = list(range(1, max(items) + 1))
     if sorted(items) != expected:
         raise HandoffError("INTENT.md success criteria must be contiguous from 1")
-    return {f"SC{number}": text for number, text in items.items()}
+    # Issue #392: a review can quote a criterion without the markers of its sub-bullet lines.
+    bare = _numbered_items(
+        _section(_common.without_sub_bullet_markers(intent), "Success criteria"), continuations=True
+    )
+    return {f"SC{number}": _common.Criterion(text, bare[number]) for number, text in items.items()}
 
 
 def _split_top_level_commas(value: str) -> List[str]:
@@ -1297,18 +1310,22 @@ def _normalize_ws(value: str) -> str:
 
 
 def task_review_observation(item: str, task_text: str) -> str:
-    """Separate an exact quoted acceptance criterion from its observed evidence."""
+    """Separate a quoted acceptance criterion from its observed evidence."""
     item = _normalize_ws(item)
     section = _common.section_body(task_text, "Acceptance criteria")
     if section is not None:
-        for criterion in _numbered_items(section, continuations=True).values():
-            quoted = _normalize_ws(criterion)
-            prefix = quoted + " — "
-            if item.startswith(prefix):
-                return item[len(prefix) :]
-            if item in {quoted, quoted + " —"}:
-                return ""
-    return item
+        # Issue #374: frozen landed bytes may repeat a criterion number. Only the
+        # criterion text matters here, so each repeated entry is still split
+        # from its evidence and the evidence gets the same checks.
+        criteria = [criterion for _number, criterion in _numbered_entries(section, continuations=True)]
+        quoted = _common.quoted_criterion(item, criteria)
+        if quoted is not None:
+            return item[quoted[1] + len(" — ") :]
+    # Issue #392: a quote can leave out the `- ` markers of the criterion's
+    # sub-bullet lines, so read the criteria again without them.
+    bare = _common.without_sub_bullet_markers(task_text)
+    return item if bare == task_text else task_review_observation(item, bare)
+
 
 
 def _verify_command(task_text: str) -> str:
@@ -1528,11 +1545,30 @@ def _validate_task_graph(
             if _task_wave(tasks[dependency], dependency) > wave:
                 raise HandoffError(f"{task_id} depends on later-wave {dependency}")
 
+    # `supersedes` retires the regression Verify of an earlier task: the same overlap rule selects both.
+    for task_id, text in tasks.items():
+        superseded = _strict_frontmatter(text, task_id).get("supersedes", [])
+        if (
+            not isinstance(superseded, list)
+            or any(not re.fullmatch(r"T\d{3}", item) for item in superseded)
+            or len(superseded) != len(set(superseded))
+        ):
+            raise HandoffError(f"{task_id} supersedes must be a list of different task ids, for example [T001]")
+        for earlier in superseded:
+            if earlier not in tasks:
+                raise HandoffError(f"{task_id} supersedes unknown task {earlier}")
+            if task_waves[earlier] >= task_waves[task_id]:
+                raise HandoffError(f"{task_id} supersedes {earlier}, which is not in an earlier wave")
+            if task_repos[earlier] != task_repos[task_id]:
+                raise HandoffError(f"{task_id} supersedes {earlier}, which is in another repo")
+            if not _common.overlapping_paths(task_files[earlier], task_files[task_id]):
+                raise HandoffError(f"{task_id} supersedes {earlier}, which shares no declared file with it")
+
     for index, left in enumerate(task_ids):
         for right in task_ids[index + 1 :]:
             if task_waves[left] != task_waves[right] or task_repos[left] != task_repos[right]:
                 continue
-            overlap = sorted(set(task_files[left]) & set(task_files[right]))
+            overlap = _common.overlapping_paths(task_files[left], task_files[right])
             if overlap:
                 if (
                     _task_scalar(tasks[left], left, "status") == "done"
@@ -1746,7 +1782,24 @@ def validate_roadmap(
 ) -> Dict[str, object]:
     """Validate roadmap structure and dependency ordering."""
 
-    _require_state(root, "roadmap", "active", project_dir)
+    # A milestone-boundary re-slice keeps its entering inspect or define state.
+    _require_state_one_of(
+        root,
+        {("roadmap", "active"), ("inspect", "active"), ("define", "active")},
+        project_dir,
+    )
+    if _require_pipeline(root, project_dir)["phase"] == "define":
+        if __package__:
+            from . import build_recovery
+        else:
+            import build_recovery
+        try:
+            # Define entered again after intent approval is not a boundary.
+            reopened = (build_recovery.context(root.resolve()) or {}).get("active")
+        except PipelineStateError as error:
+            raise HandoffError(str(error)) from error
+        if reopened:
+            raise HandoffError("roadmap re-slice is not legal after intent approval")
     relative = f"{project_dir}/ROADMAP.md"
     text = _read(root, relative)
     if re.search(r"(?m)^## Wave |^\|\s*Task\s*\||^Files:\s*", text):
@@ -2045,25 +2098,28 @@ def validate_wave_evidence(
     if enforce_plan_tasks:
         if reviewed_tasks != expected_tasks:
             raise HandoffError(
-                f"{name} must review exactly {', '.join(expected_tasks)} in plan order"
+                f"{name} must review exactly {', '.join(expected_tasks)} in task id order"
             )
     else:
         unknown = [task_id for task_id in reviewed_tasks if task_id not in expected_tasks]
         if unknown:
             raise HandoffError(
-                f"{name} must review exactly {', '.join(expected_tasks)} in plan order"
+                f"{name} must review exactly {', '.join(expected_tasks)} in task id order"
             )
         plan_order = [task_id for task_id in expected_tasks if task_id in reviewed_tasks]
         if reviewed_tasks != plan_order:
             raise HandoffError(
-                f"{name} must review exactly {', '.join(expected_tasks)} in plan order"
+                f"{name} must review exactly {', '.join(expected_tasks)} in task id order"
             )
     task_verdicts = []
     for heading_index, heading in task_headings:
         task_id = heading.group("task")
         expected_title = _normalize_ws(_task_scalar(tasks[task_id], task_id, "title"))
         if _normalize_ws(heading.group("title")) != expected_title:
-            raise HandoffError(f"{name} title for {task_id} differs from task file")
+            raise HandoffError(
+                f"{name} title for {task_id} differs from task file; "
+                f"expected the exact `title:` value: {expected_title}"
+            )
         end = next(
             (
                 index
@@ -2080,7 +2136,10 @@ def validate_wave_evidence(
             if line.strip().startswith(f"- {marker} ")
         ]
         if not evidence:
-            raise HandoffError(f"{name} task {task_id} lacks {verdict} evidence")
+            raise HandoffError(
+                f"{name} task {task_id} lacks {verdict} evidence; "
+                f"add a line that starts with `- {marker} ` under its heading"
+            )
         for item in evidence:
             item = task_review_observation(item, tasks[task_id])
             _non_placeholder(item, f"{name} task {task_id} {verdict} evidence")
@@ -2132,7 +2191,7 @@ def validate_wave_evidence(
             sc_id in criteria
             and (
                 not separator
-                or _normalize_ws(heading_text) != _normalize_ws(criteria[sc_id])
+                or not _common.quotes_criterion(heading_text, criteria[sc_id])
             )
         ):
             raise HandoffError(f"{name} {sc_id} heading text differs from INTENT.md")
@@ -2150,7 +2209,10 @@ def validate_wave_evidence(
             if line.strip().startswith(f"- {marker} ")
         ]
         if not evidence:
-            raise HandoffError(f"{name} {sc_id} lacks {verdict} evidence")
+            raise HandoffError(
+                f"{name} {sc_id} lacks {verdict} evidence; "
+                f"add a line that starts with `- {marker} ` under its heading"
+            )
         for item in evidence:
             _non_placeholder(item, f"{name} {sc_id} {verdict} evidence")
         verdicts[sc_id] = verdict
@@ -2230,7 +2292,7 @@ def validate_final(
     verdicts: Dict[str, str] = {}
     for index, heading in enumerate(blocks):
         sc_id = heading.group("id")
-        if _normalize_ws(heading.group("title")) != _normalize_ws(criteria[sc_id]):
+        if not _common.quotes_criterion(heading.group("title"), criteria[sc_id]):
             raise HandoffError(f"FINAL.md {sc_id} heading text differs from INTENT.md")
         end = blocks[index + 1].start() if index + 1 < len(blocks) else len(text)
         block = text[heading.end() : end]

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

@@ -100,13 +100,15 @@ def _supplied_contract(repo: Path, task: Path, token: str) -> bool:
     return path.is_file() and path.resolve() == repo.resolve() / token
 
 
+def _pipeline_workspace_path(repo: Path, task: Path, token: str) -> bool:
+    track = _project_track(task, repo)
+    return track is not None and token.startswith(
+        tuple(f"{track}/{name}/" for name in PIPELINE_WORKSPACE_DIRS))
+
+
 def _pipeline_workspace_file(repo: Path, task: Path, token: str) -> bool:
     """Pipeline-owned paths may exist only in the working tree before checkpoint."""
-    track = _project_track(task, repo)
-    if track is None:
-        return False
-    prefixes = tuple(f"{track}/{name}/" for name in PIPELINE_WORKSPACE_DIRS)
-    if not any(token.startswith(prefix) for prefix in prefixes):
+    if not _pipeline_workspace_path(repo, task, token):
         return False
     path = repo / token
     return path.is_file() and path.resolve() == repo.resolve() / token
@@ -277,7 +279,7 @@ def _verify_tokens(
 
 
 def _member_bases(root: Path):
-    """Resolve a member name to (checkout, origin/main SHA), reading MEMBERS.md once."""
+    """Resolve a member name to (checkout, base SHA), reading MEMBERS.md once."""
     cache: Dict[str, Optional[Tuple[Path, str]]] = {}
 
     def locate(name: str) -> Optional[Tuple[Path, str]]:
@@ -290,21 +292,22 @@ def _member_bases(root: Path):
                 except ImportError:  # pragma: no cover - package import used by tests
                     from scripts import members
             try:
-                listed = {member["name"]: Path(member["checkout"]) for member in members.read_members(root)}
-                checkout = listed.get(name)
-                if checkout is None:
+                listed = {member["name"]: member for member in members.read_members(root)}
+                if name not in listed:
                     cache[name] = None
                 else:
+                    checkout = Path(listed[name]["checkout"])
                     # A build lock selects the bound tip, including during Plan recovery;
-                    # without the lock, use origin/main before the first build start.
+                    # without the lock, use the member's recorded default branch on origin
+                    # before the first build start.
                     lock = root / members.LOCK_PATH
                     locked = [entry for entry in (json.loads(lock.read_text(encoding="utf-8"))["members"]
                                                   if lock.is_file() else []) if entry["name"] == name]
                     if locked:
                         cache[name] = (checkout, _resolve_base(checkout, f"refs/heads/{locked[0]['branch']}"))
                     else:
-                        members.require_origin_main(checkout)
-                        cache[name] = (checkout, _resolve_base(checkout, "refs/remotes/origin/main"))
+                        cache[name] = (checkout, members.require_origin_branch(
+                            checkout, members.default_branch(listed[name])))
             except (members.MembersError, BriefError) as error:
                 raise BriefError(f"member {name} is unavailable: {error}") from error
         return cache[name]
@@ -328,8 +331,8 @@ def _lint_task(
     checked = 0
     if fields is None:
         return task_id, [error or "invalid frontmatter"], None, checked
-    # A member task's paths resolve in the member at its origin/main, where the
-    # member bound branch starts; `repo:` absent means the coordinator.
+    # A member task's paths resolve in the member at its default branch on origin,
+    # where the member bound branch starts; `repo:` absent means the coordinator.
     git_root = repo
     member = fields.get("repo")
     if member is not None:
@@ -384,7 +387,9 @@ def _lint_task(
                     )
                     break
 
-    for name in PROSE_SECTIONS:
+    # A landed brief is history that nobody can edit: only an unlanded brief must name present paths.
+    landed = task_id in (landed_bases or {})
+    for name in () if landed else PROSE_SECTIONS:
         body = sections.get(name)
         if body is None or not _clean(body):
             continue
@@ -406,7 +411,7 @@ def _lint_task(
         block = VERIFY_BLOCK_PATTERN.search(verify_body)
         if block is None or not block.group("block").strip():
             problems.append("## Verify must contain a non-empty fenced bash block")
-        else:
+        elif not landed:
             for token in _verify_tokens(
                 block.group("block"),
                 repo=repo,
@@ -443,9 +448,10 @@ def validate_task_briefs(
 
     Plain lint uses the layer base without overrides. Plan approval and dispatch
     supply transitive dependency files for unlanded tasks and resolved historical
-    bases for landed tasks, whose immutable briefs must survive later file changes.
+    bases for landed tasks. A landed brief is immutable: its `files` scope is
+    checked at that base, and the paths its prose and Verify name are not checked.
     The caller validates the task graph and landed metadata before supplying
-    these mappings; landed tasks receive no dependency-file allowance.
+    these mappings.
     """
 
     resolved_base = _resolve_base(root, base)
@@ -476,6 +482,9 @@ def validate_task_briefs(
     for shape, task_ids in contracts.items():
         if len(task_ids) == 1:
             task_id = next(iter(task_ids))
+            # A landed brief is history: a later repair may reword the bullet in its partner.
+            if task_id in (landed_bases or {}):
+                continue
             problems.append(
                 f"{task_id}: interface contract is not shared by any other task: {shape}"
             )
@@ -587,7 +596,6 @@ def plan_validation_bases(
                 )
             except IsolationError as error:
                 raise BriefError(f"{task_id} landed task has invalid historical base: {error}") from error
-            dependency_files[task_id] = set()
     except check_handoffs.HandoffError as error:
         raise BriefError(str(error)) from error
     return tasks, dependency_files, landed_bases

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

@@ -1291,10 +1291,17 @@ def project_slug(root: Path) -> str:
     return slug or "project"
 
 
-def filled_state_template(template: str, slug: str, phase: str) -> str:
+def filled_state_template(
+    template: str, slug: str, phase: str, default_branch: str = "main"
+) -> str:
     if "<slug>" not in template:
         raise DetectError("state template missing slug placeholder")
     text = template.replace("<slug>", slug)
+    text, count = re.subn(
+        r"(?m)^default_branch: main\b", lambda _: f"default_branch: {default_branch}", text, count=1
+    )
+    if count != 1:
+        raise DetectError("state template missing default_branch: main line")
     text, count = re.subn(r"(?m)^phase: define\b", f"phase: {phase}", text, count=1)
     if count != 1:
         raise DetectError("state template missing phase: define line")
@@ -2030,6 +2037,14 @@ def initialize(
         )
         if git.returncode != 0 or git.stdout.strip() != "true":
             return {**payload, "route": "setup-repository", "wrote_state": False}
+    default_branch = _common.origin_default_branch(root)
+    if not _common.valid_default_branch(default_branch):
+        return {**payload, "wrote_state": False, "error": (
+            f"origin default branch {default_branch!r} cannot be recorded in STATE.md: "
+            "it is a GSD Path reserved name or it has a character that STATE frontmatter "
+            "cannot hold. Rename the default branch, then run "
+            "`git remote set-head origin --auto`."
+        )}
     expected = "inspect" if payload["verdict"] == "brownfield" else "define"
     if phase is None:
         phase = expected
@@ -2043,7 +2058,7 @@ def initialize(
         return payload
     write_state_anchored(
         root,
-        filled_state_template(raw, project_slug(root), phase),
+        filled_state_template(raw, project_slug(root), phase, default_branch),
         root_status,
         project_status,
     )

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

@@ -7,6 +7,7 @@ import json
 import os
 import shutil
 import sys
+import traceback
 
 # Runtime helpers must not modify their immutable installation.
 sys.dont_write_bytecode = True
@@ -33,7 +34,7 @@ def _load_pipeline_modules():
     try:
         from scripts import archive_milestone, pipeline_state, _common
         return _common, archive_milestone, pipeline_state
-    except ModuleNotFoundError as error:
+    except ImportError as error:  # a foreign `scripts` package
         if error.name not in {
             "scripts",
             "scripts.archive_milestone",
@@ -41,6 +42,13 @@ def _load_pipeline_modules():
             "scripts._common",
         }:
             raise
+        # A plain ImportError raised while a `scripts` module loaded is not a
+        # foreign package. A missing module falls back, as before.
+        if not isinstance(error, ModuleNotFoundError) and any(
+            frame.f_globals.get("__name__", "").startswith("scripts.")
+            for frame, _ in traceback.walk_tb(error.__traceback__)
+        ):
+            raise
         shared_scripts = Path(__file__).resolve().parents[2] / "gsd-path" / "scripts"
         sys.path.insert(0, str(shared_scripts))
         import archive_milestone

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

@@ -507,7 +507,8 @@ def archived_intent_criteria(archive: Path) -> dict[int, str]:
         criteria = check_handoffs._success_criteria(text)
     except check_handoffs.HandoffError as error:
         raise ArchiveError(str(error)) from error
-    return {int(key[2:]): " ".join(value.split()) for key, value in criteria.items()}
+    # Each value keeps the form without sub-bullet markers that quotes_criterion reads.
+    return {int(key[2:]): value for key, value in criteria.items()}
 
 
 def parse_final_review(archive: Path) -> tuple:
@@ -563,7 +564,7 @@ def _final_review(archive: Path) -> tuple:
     if len(headings) != len(intent_criteria):
         raise ArchiveError("FINAL.md success criteria do not exactly cover INTENT.md")
     for _, number, criterion in headings:
-        if " ".join(criterion.split()) != intent_criteria[number]:
+        if not _common.quotes_criterion(criterion, intent_criteria[number]):
             raise ArchiveError(
                 f"FINAL.md SC{number} heading text differs from archived INTENT.md"
             )
@@ -951,10 +952,10 @@ def validate_wave_review(
             (index, match.group(1), " ".join(match.group(2).split()), match.group(3))
         )
     actual = [(sc_id, text) for _, sc_id, text, _ in criterion_headings]
-    normalized_expected_criteria = [
-        (sc_id, " ".join(text.split())) for sc_id, text in expected_criteria
-    ]
-    if actual != normalized_expected_criteria:
+    if len(actual) != len(expected_criteria) or any(
+        sc_id != expected_id or not _common.quotes_criterion(text, expected)
+        for (sc_id, text), (expected_id, expected) in zip(actual, expected_criteria)
+    ):
         raise ArchiveError(
             f"{path.name} Intent coverage does not match its owned success criteria"
         )