@opengsd/gsd-path 1.4.0 → 1.6.0

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

@@ -53,6 +53,9 @@ COMMENT_PATTERN = re.compile(r"<!--.*?-->", re.DOTALL)
 BACKTICK_PATTERN = re.compile(r"`([^`\n]+)`")
 PATH_TOKEN_PATTERN = re.compile(r"[A-Za-z0-9._~/-]+")
 VERIFY_BLOCK_PATTERN = re.compile(r"```bash[ \t]*\n(?P<block>.*?)```", re.DOTALL)
+TEXT_TOOL_COMMANDS = frozenset({"awk", "egrep", "fgrep", "gawk", "grep", "gsed", "rg", "sed"})
+REGEX_PATTERN_CHARS = frozenset("|*+?[]()^$.\\")
+PIPELINE_WORKSPACE_DIRS = ("review", "discuss", "build", "plan")
 
 
 class BriefError(RuntimeError):
@@ -73,10 +76,20 @@ def _base_exists(repo: Path, base: str, path: str) -> bool:
     return _run_git(repo, "cat-file", "-e", f"{base}:{path}").returncode == 0
 
 
+def _project_track(task: Path, repo: Path) -> Optional[str]:
+    try:
+        track = task.parent.parent.relative_to(repo).as_posix()
+    except ValueError:
+        return None
+    if track not in {".project", ".project/next"}:
+        return None
+    return track
+
+
 def _supplied_contract(repo: Path, task: Path, token: str) -> bool:
     """Plan approval checkpoints these supplied inputs after the brief gate."""
-    track = task.parent.parent.relative_to(repo).as_posix()
-    if track not in {".project", ".project/next"}:
+    track = _project_track(task, repo)
+    if track is None:
         return False
     if token not in {
         f"{track}/intent/INTENT.md",
@@ -87,6 +100,20 @@ 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."""
+    if not _pipeline_workspace_path(repo, task, token):
+        return False
+    path = repo / token
+    return path.is_file() and path.resolve() == repo.resolve() / token
+
+
 _strip_yaml_comment = _common.strip_yaml_comment
 _unquote = _common.unquote
 
@@ -151,7 +178,7 @@ def _clean(body: str) -> str:
     return COMMENT_PATTERN.sub("", body).strip()
 
 
-def _looks_like_path(token: str) -> bool:
+def _slash_token_shape(token: str) -> bool:
     return (
         "/" in token
         and PATH_TOKEN_PATTERN.fullmatch(token) is not None
@@ -162,32 +189,97 @@ def _looks_like_path(token: str) -> bool:
     )
 
 
+def _last_segment_has_extension(token: str) -> bool:
+    name = PurePosixPath(token).name
+    return "." in name and not name.startswith(".")
+
+
+def _looks_like_path(
+    token: str,
+    *,
+    repo: Path,
+    git_root: Path,
+    base: str,
+    task: Path,
+) -> bool:
+    if not _slash_token_shape(token):
+        return False
+    if _last_segment_has_extension(token):
+        return True
+    if _base_exists(git_root, base, token):
+        return True
+    if _pipeline_workspace_file(repo, task, token):
+        return True
+    return False
+
+
+def _looks_like_regex_pattern(token: str) -> bool:
+    return any(character in token for character in REGEX_PATTERN_CHARS)
+
+
+def _text_tool_command(command: str) -> bool:
+    return Path(command).name.casefold() in TEXT_TOOL_COMMANDS
+
+
 def _normalize(path: str) -> str:
     return str(PurePosixPath(path))
 
 
-def _prose_tokens(body: str) -> List[str]:
+def _prose_tokens(
+    body: str,
+    *,
+    repo: Path,
+    git_root: Path,
+    base: str,
+    task: Path,
+) -> List[str]:
     cleaned = COMMENT_PATTERN.sub("", body)
-    return [
-        _normalize(match.group(1).strip())
-        for match in BACKTICK_PATTERN.finditer(cleaned)
-        if _looks_like_path(match.group(1).strip())
-    ]
+    tokens: List[str] = []
+    for match in BACKTICK_PATTERN.finditer(cleaned):
+        candidate = match.group(1).strip()
+        if _looks_like_path(
+            candidate, repo=repo, git_root=git_root, base=base, task=task
+        ):
+            tokens.append(_normalize(candidate))
+    return tokens
 
 
-def _verify_tokens(block: str) -> List[str]:
-    tokens = []
+def _verify_tokens(
+    block: str,
+    *,
+    repo: Path,
+    git_root: Path,
+    base: str,
+    task: Path,
+) -> List[str]:
+    tokens: List[str] = []
     for line in block.splitlines():
         parts = line.split()
-        for token in parts[1:]:
-            token = token.strip("\"'")
-            if _looks_like_path(token):
+        if len(parts) < 2:
+            continue
+        command = parts[0]
+        extended_grep = False
+        index = 1
+        while index < len(parts) and parts[index].startswith("-") and "=" not in parts[index]:
+            flag = parts[index]
+            if flag in {"-E", "-G"} or flag.startswith("-E"):
+                extended_grep = True
+            index += 1
+        text_tool = _text_tool_command(command)
+        for raw in parts[index:]:
+            quoted = raw.startswith(("'", '"'))
+            token = raw.strip("\"'")
+            if text_tool and quoted:
+                continue
+            if text_tool and command.casefold() == "grep" and extended_grep and _looks_like_regex_pattern(token):
+                continue
+            if _looks_like_path(token, repo=repo, git_root=git_root, base=base, task=task):
                 tokens.append(_normalize(token))
     return 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]]:
@@ -200,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]
@@ -238,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:
@@ -298,12 +391,17 @@ def _lint_task(
         body = sections.get(name)
         if body is None or not _clean(body):
             continue
-        for token in _prose_tokens(body):
+        for token in _prose_tokens(
+            body, repo=repo, git_root=git_root, base=base, task=path
+        ):
             checked += 1
             if (
                 token not in declared
                 and token not in supplied
                 and not _supplied_contract(repo, path, token)
+                and not _pipeline_workspace_file(repo, path, token)
+                # A landed brief is history: the pipeline moves its own files (build recovery, archive) later.
+                and not (task_id in (landed_bases or {}) and _pipeline_workspace_path(repo, path, token))
                 and not _base_exists(git_root, base, token)
             ):
                 problems.append(f"## {name} names a path missing at the layer base: {token}")
@@ -314,9 +412,20 @@ def _lint_task(
         if block is None or not block.group("block").strip():
             problems.append("## Verify must contain a non-empty fenced bash block")
         else:
-            for token in _verify_tokens(block.group("block")):
+            for token in _verify_tokens(
+                block.group("block"),
+                repo=repo,
+                git_root=git_root,
+                base=base,
+                task=path,
+            ):
                 checked += 1
-                if token not in declared and token not in supplied and not _base_exists(git_root, base, token):
+                if (
+                    token not in declared
+                    and token not in supplied
+                    and not _pipeline_workspace_file(repo, path, token)
+                    and not _base_exists(git_root, base, token)
+                ):
                     problems.append(f"## Verify names a path missing at the layer base: {token}")
 
     contract = None
@@ -337,9 +446,9 @@ def validate_task_briefs(
 ) -> Dict[str, object]:
     """Lint task briefs using the caller's validation bases.
 
-    Dispatch uses the layer base without overrides. Plan approval supplies
-    transitive dependency files for pending tasks and resolved historical bases
-    for landed tasks, whose immutable briefs must survive later file changes.
+    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.
     The caller validates the task graph and landed metadata before supplying
     these mappings; landed tasks receive no dependency-file allowance.
     """
@@ -381,6 +490,136 @@ def validate_task_briefs(
     return {"base": resolved_base, "checked": checked, "tasks": len(task_files)}
 
 
+def _resolve_landed_task_base(
+    task_id: str,
+    recorded_base: str,
+    recorded_member_base: object,
+    coordinator_repo: Path,
+    member_repo: Optional[Path],
+) -> str:
+    """Resolve a landed task's historical base in the repository it names."""
+    if __package__:
+        from .isolation import IsolationError, require_commit, require_full_sha
+    else:
+        try:
+            from isolation import IsolationError, require_commit, require_full_sha
+        except ModuleNotFoundError as error:
+            if error.name != "isolation":
+                raise
+            from scripts.isolation import IsolationError, require_commit, require_full_sha
+
+    recorded_full = require_full_sha(recorded_base)
+    if member_repo is None:
+        try:
+            return require_commit(coordinator_repo, recorded_full)
+        except IsolationError as error:
+            raise BriefError(
+                f"{task_id} landed task has invalid historical base: {error}"
+            ) from error
+
+    legacy_member_base = (
+        recorded_member_base is None
+        or (isinstance(recorded_member_base, str)
+            and recorded_member_base.strip().casefold() in {"", "null", "~"})
+        or (isinstance(recorded_member_base, list) and not recorded_member_base)
+    )
+    try:
+        if not legacy_member_base:
+            if not isinstance(recorded_member_base, str):
+                raise IsolationError(
+                    f"member_base must be a full 40-character SHA: {recorded_member_base}"
+                )
+            member_full = require_full_sha(recorded_member_base)
+            return require_commit(member_repo, member_full)
+        try:
+            return require_commit(coordinator_repo, recorded_full)
+        except IsolationError:
+            return require_commit(member_repo, recorded_full)
+    except IsolationError as error:
+        raise BriefError(
+            f"{task_id} landed task has invalid historical base: {error}"
+        ) from error
+
+def plan_validation_bases(
+    root: Path, project_dir: str, member_base=None, *, initial: bool = True,
+) -> Tuple[Dict[str, str], Dict[str, Set[str]], Dict[str, str]]:
+    """Share dependency files and landed historical bases across approval and dispatch.
+
+    Approval requires unlanded tasks to start clean. Dispatch may run beside
+    in-flight tasks, while retaining the same graph and path checks.
+    """
+    if __package__:
+        from . import check_handoffs
+        from .isolation import IsolationError
+    else:
+        try:
+            import check_handoffs
+            from isolation import IsolationError
+        except ModuleNotFoundError as error:
+            if error.name not in {"check_handoffs", "isolation"}:
+                raise
+            from scripts import check_handoffs
+            from scripts.isolation import IsolationError
+    if member_base is None:
+        member_base = _member_bases(root)
+    try:
+        tasks, dependency_files = check_handoffs.plan_brief_inputs(
+            root, project_dir, initial=initial
+        )
+        landed_bases: Dict[str, str] = {}
+        for task_id, text in tasks.items():
+            if check_handoffs._task_scalar(text, task_id, "status") != "done":
+                continue
+            agent = check_handoffs._task_scalar(text, task_id, "agent")
+            if agent in {"", "null"}:
+                raise BriefError(f"{task_id} landed task has no recorded agent")
+            fields = check_handoffs._strict_frontmatter(text, task_id)
+            member = fields.get("repo")
+            base_repo = root
+            if member is not None:
+                located = member_base(member) if isinstance(member, str) and member else None
+                if located is None:
+                    raise BriefError(f"repo: names no member in MEMBERS.md: {member}")
+                base_repo = located[0]
+            recorded_base = check_handoffs._task_scalar(text, task_id, "base")
+            try:
+                landed_bases[task_id] = _resolve_landed_task_base(
+                    task_id,
+                    recorded_base,
+                    fields.get("member_base") if member is not None else None,
+                    root,
+                    base_repo if member is not None else None,
+                )
+            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
+
+
+def validate_plan_task_briefs(
+    root: Path,
+    base: str,
+    project_dir: str = ".project",
+    tasks_dir: Optional[str] = None,
+) -> Dict[str, object]:
+    """Dispatch lint with dependency files and landed historical bases."""
+    member_base = _member_bases(root)
+    _, dependency_files, landed_bases = plan_validation_bases(
+        root, project_dir, member_base, initial=False
+    )
+    resolved_tasks_dir = tasks_dir or f"{project_dir}/tasks"
+    return validate_task_briefs(
+        root,
+        base,
+        resolved_tasks_dir,
+        dependency_files=dependency_files,
+        landed_bases=landed_bases,
+        member_base=member_base,
+    )
+
+
 def _tasks_dir(value: str) -> str:
     """Argparse type for --tasks-dir: a relative POSIX-style path."""
 
@@ -411,15 +650,37 @@ def parser() -> argparse.ArgumentParser:
         help="relative POSIX-style directory under --repo holding the task files "
         "(default: .project/tasks)",
     )
+    argument_parser.add_argument(
+        "--project-dir",
+        default=None,
+        help="apply plan dependency files and landed-task bases for this track "
+        "(inferred from --tasks-dir when its sibling plan/PLAN.md exists)",
+    )
     return argument_parser
 
 
 def main(argv: Optional[Sequence[str]] = None) -> int:
     arguments = parser().parse_args(argv)
     try:
-        result = validate_task_briefs(
-            arguments.repo.resolve(), arguments.base, arguments.tasks_dir
-        )
+        root = arguments.repo.resolve()
+        project_dir = arguments.project_dir
+        if project_dir is None:
+            tasks_path = PurePosixPath(arguments.tasks_dir)
+            if tasks_path.name == "tasks" and len(tasks_path.parts) > 1:
+                track = tasks_path.parent.as_posix()
+                if (root / track / "plan/PLAN.md").is_file():
+                    project_dir = track
+        if project_dir is not None:
+            result = validate_plan_task_briefs(
+                root,
+                arguments.base,
+                project_dir,
+                None if arguments.tasks_dir == DEFAULT_TASKS_DIR else arguments.tasks_dir,
+            )
+        else:
+            result = validate_task_briefs(
+                root, arguments.base, arguments.tasks_dir
+            )
     except BriefError as error:
         print(f"task brief validation failed: {error}", file=sys.stderr)
         return 1