@opengsd/gsd-path 1.3.1 → 1.5.0

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

@@ -12,10 +12,13 @@ sys.dont_write_bytecode = True
 from pathlib import Path, PurePosixPath
 from typing import Dict, List, Optional, Sequence, Set, Tuple
 
-try:
-    import _common
-except ImportError:  # pragma: no cover - package import used by tests
-    from scripts import _common
+if __package__:
+    from . import _common
+else:
+    try:
+        import _common
+    except ImportError:  # pragma: no cover - package import used by tests
+        from scripts import _common
 
 
 DEFAULT_TASKS_DIR = ".project/tasks"
@@ -50,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):
@@ -70,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",
@@ -84,6 +100,18 @@ def _supplied_contract(repo: Path, task: Path, token: str) -> bool:
     return path.is_file() and path.resolve() == repo.resolve() / token
 
 
+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):
+        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
 
@@ -148,7 +176,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
@@ -159,34 +187,136 @@ 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."""
+    cache: Dict[str, Optional[Tuple[Path, str]]] = {}
+
+    def locate(name: str) -> Optional[Tuple[Path, str]]:
+        if name not in cache:
+            if __package__:
+                from . import members
+            else:
+                try:
+                    import members
+                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:
+                    cache[name] = None
+                else:
+                    # A build lock selects the bound tip, including during Plan recovery;
+                    # without the lock, use origin/main 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"))
+            except (members.MembersError, BriefError) as error:
+                raise BriefError(f"member {name} is unavailable: {error}") from error
+        return cache[name]
+
+    return locate
+
+
 def _lint_task(
     repo: Path, base: str, path: Path,
     dependency_files: Optional[Dict[str, Set[str]]] = None,
     landed_bases: Optional[Dict[str, str]] = None,
+    member_base=None,
 ) -> Tuple[str, List[str], Optional[str], int]:
     text = path.read_text(encoding="utf-8")
     fields, error = _frontmatter(text)
@@ -198,6 +328,15 @@ 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.
+    git_root = repo
+    member = fields.get("repo")
+    if member is not None:
+        located = member_base(member) if isinstance(member, str) and member and member_base else None
+        if located is None:
+            return task_id, [f"repo: names no member in MEMBERS.md: {member}"], None, checked
+        git_root, base = located[0], (landed_bases or {}).get(task_id, located[1])
 
     for field in REQUIRED_FIELDS:
         if field not in fields:
@@ -237,7 +376,7 @@ def _lint_task(
             for parent in candidate.parents:
                 if str(parent) == ".":
                     break
-                kind = _run_git(repo, "cat-file", "-t", f"{base}:{parent}")
+                kind = _run_git(git_root, "cat-file", "-t", f"{base}:{parent}")
                 if kind.returncode == 0 and kind.stdout.strip() != "tree":
                     problems.append(
                         f"files entry {normalized} has non-directory ancestor "
@@ -249,13 +388,16 @@ 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 _base_exists(repo, base, token)
+                and not _pipeline_workspace_file(repo, path, token)
+                and not _base_exists(git_root, base, token)
             ):
                 problems.append(f"## {name} names a path missing at the layer base: {token}")
 
@@ -265,9 +407,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(repo, 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
@@ -284,12 +437,13 @@ def validate_task_briefs(
     root: Path, base: str, tasks_dir: str = DEFAULT_TASKS_DIR,
     *, dependency_files: Optional[Dict[str, Set[str]]] = None,
     landed_bases: Optional[Dict[str, str]] = None,
+    member_base=None,
 ) -> 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.
     """
@@ -305,9 +459,11 @@ def validate_task_briefs(
     task_files = sorted(tasks_path.glob("*.md"))
     if not task_files:
         raise BriefError(f"no task briefs found in {tasks_dir}")
+    if member_base is None:
+        member_base = _member_bases(root)
     for path in task_files:
         task_id, task_problems, contract, task_checked = _lint_task(
-            root, resolved_base, path, dependency_files, landed_bases
+            root, resolved_base, path, dependency_files, landed_bases, member_base
         )
         problems.extend(f"{task_id}: {problem}" for problem in task_problems)
         if contract is not None:
@@ -329,6 +485,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."""
 
@@ -359,15 +645,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