@opengsd/gsd-path 1.6.1 → 1.7.0

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

@@ -1,16 +1,24 @@
 #!/usr/bin/env python3
 # gsd-path project runtime
-"""Lint build task briefs against the layer base before dispatch."""
+"""Lint build task briefs against the layer base before dispatch.
+
+The check is read-only and idempotent: git queries and file reads, no writes.
+Progress goes to stderr (one line every 20 tasks); stdout is exactly the final
+JSON. A host timeout with no output is not a contract verdict — rerun with a
+larger timeout; the checker never hangs on state it changed itself.
+"""
 
 import argparse
+import functools
 import json
 import re
 import sys
+import time
 
 # 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
+from typing import Dict, FrozenSet, List, Optional, Sequence, Set, Tuple
 
 if __package__:
     from . import _common
@@ -73,7 +81,57 @@ def _resolve_base(repo: Path, base: str) -> str:
 
 
 def _base_exists(repo: Path, base: str, path: str) -> bool:
-    return _run_git(repo, "cat-file", "-e", f"{base}:{path}").returncode == 0
+    files, directories = _base_listing(repo, base)
+    return path in files or path in directories
+
+
+@functools.lru_cache(maxsize=None)
+def _base_listing(repo: Path, base: str) -> Tuple[FrozenSet[str], FrozenSet[str]]:
+    """Every path an object occupies at the immutable `base` commit.
+
+    One `ls-tree` pair per (repository, base) replaces a `cat-file` subprocess
+    per queried path: a commit is fixed, so its listings never change mid-run.
+    The file set names blobs and symlinks, plus submodule gitlinks whose commit
+    exists in this repository; the directory set names trees.
+    `cat-file -e <base>:<path>` succeeded exactly when the path is in either
+    set, and the ancestor check treated a path as a non-directory ancestor
+    exactly when it is in the file set — a gitlink counted only while its
+    commit object was present, so that property is preserved per gitlink.
+    """
+    files: Set[str] = set()
+    gitlinks: List[Tuple[str, str]] = []
+    result = _run_git(repo, "-c", "core.quotepath=false", "ls-tree", "-r", "-z", base)
+    if result.returncode != 0:
+        raise BriefError(f"cannot list the layer base {base}: {result.stderr.strip()}")
+    for entry in result.stdout.split("\0"):
+        if not entry:
+            continue
+        meta, separator, path = entry.partition("\t")
+        if not separator:
+            continue
+        mode, kind, sha = meta.split()
+        if kind == "commit":
+            gitlinks.append((sha, path))
+        else:
+            files.add(path)
+    present: Dict[str, bool] = {}
+
+    def gitlink_present(sha: str) -> bool:
+        if sha not in present:
+            present[sha] = _run_git(repo, "cat-file", "-e", sha).returncode == 0
+        return present[sha]
+
+    files.update(path for sha, path in gitlinks if gitlink_present(sha))
+    directories_result = _run_git(
+        repo, "-c", "core.quotepath=false", "ls-tree", "-r", "-d", "-z", "--name-only", base)
+    if directories_result.returncode != 0:
+        raise BriefError(
+            f"cannot list the layer base {base}: {directories_result.stderr.strip()}")
+    # `ls-tree -d` also lists gitlinks; they are never directories.
+    directories = frozenset(
+        path for path in directories_result.stdout.split("\0") if path
+    ) - {path for _, path in gitlinks}
+    return frozenset(files), directories
 
 
 def _project_track(task: Path, repo: Path) -> Optional[str]:
@@ -326,6 +384,9 @@ def _lint_task(
     task_id = path.stem
     if fields and isinstance(fields.get("id"), str):
         task_id = fields["id"]  # type: ignore[assignment]
+    # The coordinator's own layer base, before any landed or member override: a
+    # member task's `coordinator:` reads resolve here (#471).
+    coordinator_base = base
     base = (landed_bases or {}).get(task_id, base)
     problems: List[str] = []
     checked = 0
@@ -370,17 +431,28 @@ def _lint_task(
             if ".." in candidate.parts:
                 problems.append(f"files entry must not contain '..': {entry}")
                 continue
+            if ": " in entry or ":" in entry.split("/", 1)[0]:
+                problems.append(
+                    f"files entries are repository-local write scope; a "
+                    f"repository-qualified reference is a read: {entry}")
+                continue
             normalized = str(candidate)
             declared.add(normalized)
             checked += 1
             if ".git" in candidate.parts:
                 problems.append(f"files entry must not enter .git: {normalized}")
                 continue
+            if candidate.parts[0] == ".project":
+                # Bookkeeping territory: a landed task file under .project/ is
+                # unsupported at ship and cannot be removed during it (#466).
+                problems.append(
+                    f"files entry must stay out of .project/: {normalized}")
+                continue
+            files_at_base, _ = _base_listing(git_root, base)
             for parent in candidate.parents:
                 if str(parent) == ".":
                     break
-                kind = _run_git(git_root, "cat-file", "-t", f"{base}:{parent}")
-                if kind.returncode == 0 and kind.stdout.strip() != "tree":
+                if str(parent) in files_at_base:
                     problems.append(
                         f"files entry {normalized} has non-directory ancestor "
                         f"{parent} at the layer base"
@@ -389,6 +461,53 @@ def _lint_task(
 
     # A landed brief is history that nobody can edit: only an unlanded brief must name present paths.
     landed = task_id in (landed_bases or {})
+    # Repository-qualified read-only inputs (#471): `reads:` holds `repo: path`
+    # entries resolved in that repository at the same base its own briefs use.
+    read_paths: Set[str] = set()
+    reads = None if landed else fields.get("reads")
+    if reads is not None and not isinstance(reads, list):
+        problems.append("frontmatter reads must be a list")
+        reads = None
+    for entry in reads or []:
+        checked += 1
+        if not isinstance(entry, str) or ": " not in entry:
+            problems.append(f"reads entry must be `repo: path`: {entry!r}")
+            continue
+        name, _, read_path = entry.partition(": ")
+        candidate = PurePosixPath(read_path)
+        if candidate.is_absolute() or ".." in candidate.parts:
+            problems.append(f"reads entry is not repo-relative: {entry}")
+            continue
+        normalized = str(candidate)
+        read_paths.add(normalized)
+        if ".git" in candidate.parts:
+            problems.append(f"reads entry must not enter .git: {normalized}")
+            continue
+        if member is None:
+            # A coordinator task may read from any member of this project.
+            located = member_base(name) if member_base else None
+            if located is None:
+                problems.append(
+                    f"reads entry names no member in MEMBERS.md: {name}: {normalized}")
+                continue
+            read_root, read_base = located
+        elif name == "coordinator":
+            # A member task may read the coordinator at its own layer base.
+            read_root, read_base = repo, coordinator_base
+        else:
+            # Cross-repository reads are read-only (#471): any member of the
+            # project may be named, resolved at that member's own base.
+            located_other = member_base(name) if member_base else None
+            if located_other is None:
+                problems.append(
+                    f"reads entry names no member in MEMBERS.md: {name}: {normalized}")
+                continue
+            read_root, read_base = located_other
+        if not _base_exists(read_root, str(read_base), normalized):
+            problems.append(
+                f"reads entry {name}: {normalized} is missing at repository {name} "
+                f"base {read_base}")
+
     for name in () if landed else PROSE_SECTIONS:
         body = sections.get(name)
         if body is None or not _clean(body):
@@ -400,6 +519,7 @@ def _lint_task(
             if (
                 token not in declared
                 and token not in supplied
+                and token not in read_paths
                 and not _supplied_contract(repo, path, token)
                 and not _pipeline_workspace_file(repo, path, token)
                 and not _base_exists(git_root, base, token)
@@ -423,6 +543,7 @@ def _lint_task(
                 if (
                     token not in declared
                     and token not in supplied
+                    and token not in read_paths
                     and not _pipeline_workspace_file(repo, path, token)
                     and not _base_exists(git_root, base, token)
                 ):
@@ -467,16 +588,18 @@ def validate_task_briefs(
         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:
+    started = time.monotonic()
+    for number, path in enumerate(task_files, start=1):
+        if number % 20 == 0:
+            print(f"check_task_briefs: {number}/{len(task_files)} tasks",
+                  file=sys.stderr, flush=True)
         task_id, task_problems, contract, task_checked = _lint_task(
             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:
-            for entry in re.split(r"(?m)^-[ \t]+", contract):
-                shape = " ".join(entry.split())
-                if shape:
-                    contracts.setdefault(shape, set()).add(task_id)
+            for shape in _common.contract_shapes(contract):
+                contracts.setdefault(shape, set()).add(task_id)
         checked += task_checked
 
     for shape, task_ids in contracts.items():
@@ -491,7 +614,8 @@ def validate_task_briefs(
 
     if problems:
         raise BriefError("\n".join(problems))
-    return {"base": resolved_base, "checked": checked, "tasks": len(task_files)}
+    return {"base": resolved_base, "checked": checked, "tasks": len(task_files),
+            "elapsed_seconds": round(time.monotonic() - started, 3)}
 
 
 def _resolve_landed_task_base(

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

@@ -1034,6 +1034,19 @@ def review_cycle_counts(archive: Path) -> Sequence[int]:
         repair_introductions[receipt.task] = (receipt.wave, receipt.cycle)
     wave_artifacts = archive_milestone.canonical_wave_files(archive / "review")
     archive_milestone.validate_wave_skeptic_files(archive / "review", wave_depths, wave_artifacts)
+    # A repair wave — every task of the wave carries a Review findings section —
+    # is judged by the next review cycle of its source wave, never by an
+    # artifact of its own (build-native.md); an artifact it does have is still
+    # validated below. The heading test matches build_state's parsed-section
+    # rule, so a template comment mentioning the section does not qualify.
+    repair_waves = {
+        wave for wave in wave_numbers
+        if wave_tasks[wave]
+        and all(
+            re.search(r"(?m)^## Review findings\s*$", task_texts[task_id])
+            for task_id, _ in wave_tasks[wave]
+        )
+    }
     for path, wave, cycle, lens in wave_artifacts:
         if lens == "panel":
             artifacts.setdefault(wave, {}).setdefault(cycle, {})[lens] = path
@@ -1049,7 +1062,9 @@ def review_cycle_counts(archive: Path) -> Sequence[int]:
         if verdict not in {"pass", "blocked"}:
             raise ArchiveError(f"{path.name} has an invalid wave verdict")
         artifacts.setdefault(wave, {}).setdefault(cycle, {})[lens] = path
-    if sorted(artifacts) != wave_numbers:
+    if any(wave not in wave_numbers for wave in artifacts) or any(
+        wave not in artifacts for wave in wave_numbers if wave not in repair_waves
+    ):
         raise ArchiveError("review cycle waves do not match PLAN.md")
     for receipt in repair_receipts:
         if receipt.wave not in artifacts or receipt.cycle not in artifacts[receipt.wave]:
@@ -1065,7 +1080,7 @@ def review_cycle_counts(archive: Path) -> Sequence[int]:
             )
 
     counts = []
-    for wave in wave_numbers:
+    for wave in sorted(artifacts):
         cycles = artifacts[wave]
         if sorted(cycles) != list(range(1, max(cycles) + 1)):
             raise ArchiveError(f"review cycles for wave {wave} are not contiguous")
@@ -1128,14 +1143,29 @@ def review_cycle_counts(archive: Path) -> Sequence[int]:
                         is_last_cycle=cycle == max(cycles),
                     )
                 )
+            if cycle != max(cycles) and "blocked" not in wave_verdicts[cycle]:
+                # A superseded pass cycle is allowed only when it could not close
+                # the wave: it fails the checks a last cycle must pass.
+                try:
+                    for path, depth, lens in expected:
+                        validate_wave_review(
+                            path,
+                            expected_tasks,
+                            wave_criteria[wave],
+                            depth,
+                            lens,
+                            task_texts,
+                            is_last_cycle=True,
+                        )
+                except ArchiveError:
+                    pass
+                else:
+                    raise ArchiveError(
+                        f"superseded review cycle {cycle} for wave {wave} "
+                        "must include a blocked Wave verdict"
+                    )
 
         last_cycle = max(cycles)
-        for cycle, verdicts in wave_verdicts.items():
-            if cycle != last_cycle and "blocked" not in verdicts:
-                raise ArchiveError(
-                    f"superseded review cycle {cycle} for wave {wave} "
-                    "must include a blocked Wave verdict"
-                )
         if any(verdict != "pass" for verdict in wave_verdicts[last_cycle]):
             raise ArchiveError(f"last review cycle for wave {wave} did not pass")
         if any(task_verdict != "pass" for task_verdict in task_verdicts[last_cycle]):
@@ -1211,8 +1241,9 @@ def render_manifest(repo: Path) -> dict:
     )
     listed_contents = "\n".join(f"- {path}" for path in archive_file_inventory(archive))
     cycle_text = "/".join(str(cycle) for cycle in cycles)
+    wave_numbers, _wave_depths = plan_wave_depths((archive / "plan" / "PLAN.md").read_text(encoding="utf-8"))
     count_text = (
-        f"{len(cycles)}  Tasks: {len(tasks)} done / {len(tasks)} total  "
+        f"{len(wave_numbers)}  Tasks: {len(tasks)} done / {len(tasks)} total  "
         f"Review cycles used: {cycle_text}"
         + (f"  Attested: {attested}" if attested else "")
     )
@@ -1273,7 +1304,12 @@ def validate_manifest(project: Path, archive: Path, state: PipelineState) -> tup
     validate_gap_reviews(archive, reviewed_head)
     task_files, attested = archive_milestone.landed_task_evidence(project, archive / "tasks", reviewed_head)
     cycle_counts = review_cycle_counts(archive)
-    wave_count = len(cycle_counts)
+    # Waves counts PLAN waves; an unreviewed repair wave contributes no cycle
+    # but is still a wave, so the count comes from the PLAN, not the cycles.
+    manifest_wave_numbers, _manifest_depths = plan_wave_depths(
+        (archive / "plan" / "PLAN.md").read_text(encoding="utf-8")
+    )
+    wave_count = len(manifest_wave_numbers)
     counts = re.fullmatch(
         r"(\d+)\s+Tasks:\s+(\d+) done / (\d+) total\s+Review cycles used:\s+([1-9]\d*(?:/[1-9]\d*)*)"
         r"(?:\s+Attested:\s+([1-9]\d*))?",

package/skills/gsd-path-build/scripts/dispatch_driver.py

@@ -247,7 +247,8 @@ def open_native_shell(primary: Path, *, task_id: str, base: str, worktree: str,
                       task_branch: Optional[str], mode: str, wave: Optional[int] = None,
                       title: Optional[str] = None, files: Optional[List[str]] = None,
                       sidecar: Optional[object] = None, member: Optional[str] = None,
-                      member_base: Optional[str] = None, contract_file: Optional[str] = None) -> None:
+                      member_base: Optional[str] = None, contract_file: Optional[str] = None,
+                      agent: Optional[str] = None) -> None:
     """Open a dispatch attempt record for a host-spawned coder before it runs."""
     root = records_root(primary)
     root.mkdir(parents=True, exist_ok=True)
@@ -277,6 +278,8 @@ def open_native_shell(primary: Path, *, task_id: str, base: str, worktree: str,
         record["member_base"] = member_base
     if contract_file is not None:
         record["contract_file"] = contract_file
+    if agent is not None:
+        record["agent"] = agent
     task_dir = root / task_id
     if not should_open_native_shell(root, task_id, base):
         attempts = sorted(task_dir.glob("attempt-*/state.json"),
@@ -355,6 +358,7 @@ def record_native_member_activation(coordinator: Path, activation: Dict[str, obj
         member=str(activation["member"]),
         member_base=str(activation["member_base"]),
         contract_file=task_file,
+        agent=str(activation["agent"]),
     )
 
 
@@ -720,6 +724,19 @@ def state_from_task(primary: Path, task_id: str) -> Dict[str, object]:
             "sidecar": sidecar}
 
 
+def finish_receipt(receipt: Dict[str, object]) -> Dict[str, object]:
+    """The finish result: landed, question, or blocked — always with a visible cause (#469)."""
+    if receipt.get("landed"):
+        return {**receipt, "status": "landed"}
+    if receipt.get("questions"):
+        return {**receipt, "status": "question"}
+    result = {**receipt, "status": "blocked"}
+    if not receipt.get("blocked"):
+        result["reason"] = (
+            "task did not land and no blocked entry was recorded; inspect the task Log")
+    return result
+
+
 def finish_task(primary: Path, state: Dict[str, object]) -> Dict[str, object]:
     """Verify in the isolate, land, record the ledger, retire. Returns the landing receipt."""
     landing = land_task(primary, state)
@@ -761,15 +778,23 @@ def land_task(primary: Path, state: Dict[str, object]) -> Dict[str, object]:
         except isolation.IsolationError as error:
             raise DriverStop(str(error), task=task_id) from error
         execution, reruns = landing_verify(command, regressions, sidecar_path)
+        # The serial Verify runs in the sidecar, not the task checkout; `cwd` names the
+        # directory the command saw, `worktree` the task checkout it will land on.
+        execution_dir = sidecar_path
+        execution_base = base
         location = f"sidecar {sidecar['branch']}"
         isolation.clean_verify(primary, sidecar_path, base, str(sidecar["branch"]))
         isolation.retire(primary, sidecar_path, str(sidecar["branch"]), False)
     else:
         execution, reruns = landing_verify(command, regressions, worktree)
+        execution_dir = worktree
+        # A member Verify starts from the member repository's base, not the coordinator's.
+        execution_base = str(state["member_base"]) if state["mode"] == "member" else base
         location = f"isolate {state['task_branch']}"
     passed = execution["exit_code"] == 0
     broken = [item for item in reruns if item["exit_code"]]
-    execution.update({"worktree": str(worktree), "location": location})
+    execution.update({"worktree": str(worktree), "cwd": str(execution_dir),
+                      "base": execution_base, "location": location})
     evidence_dir = (Path(str(state["_path"])).parent if state.get("_path")
                     else records_root(primary) / task_id / f"manual-{now().replace(':', '')}")
     evidence_dir.mkdir(parents=True, exist_ok=True)
@@ -2591,7 +2616,7 @@ def main(argv=None) -> int:
             else:  # a coder dispatched by hand: derive the isolate from the task frontmatter
                 current.receipt["landed"].append(
                     finish_task(primary, native or state_from_task(primary, arguments.task_id)))
-            result = {**current.receipt, "status": "landed" if current.receipt["landed"] else "blocked"}
+            result = finish_receipt(current.receipt)
         elif arguments.action == "answer":
             result = answer(primary, arguments.task_id, arguments.answer)
         elif arguments.action == 'reassign-model':