@opengsd/gsd-path 1.3.1 → 1.4.0

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

@@ -12,12 +12,14 @@ Verdicts:
 - owned — `.project/` is a real directory with a regular `STATE.md` and no
   unsafe project paths; route by that file, not detection
 - orphan — `.project/` is unsafe, or it contains an entry without a safe
-  regular `STATE.md`; the initializer's regular temporary state file is
-  recoverable and does not make the project orphaned
-- brownfield — no owned state, `.project/` empty or absent, and at least one
-  in-scope signal (package/build manifest, source file, tracked signal in
-  git, or substantive system documentation)
-- greenfield — no owned state, `.project/` empty or absent, and no signal
+  regular `STATE.md`; the initializer's regular temporary state file and an
+  ignored, untracked regular `.DS_Store` are exceptions
+- brownfield — no owned state, `.project/` empty, absent, or containing only
+  an ignored `.DS_Store`, and at least one in-scope signal (package/build
+  manifest, source file, tracked signal in git, or substantive system
+  documentation)
+- greenfield — no owned state, `.project/` empty, absent, or containing only
+  an ignored `.DS_Store`, and no signal
 
 Ignored path components: `.git`, `node_modules`, vendored/generated trees,
 build output, and managed GSD Path installation artifacts. `.project/` is
@@ -41,6 +43,11 @@ from datetime import date
 from pathlib import Path, PurePosixPath, PureWindowsPath
 from typing import Iterable, NamedTuple, Optional, Sequence
 
+try:
+    from . import _common
+except ImportError:
+    import _common
+
 try:
     import fcntl
 
@@ -961,6 +968,26 @@ def is_staged_skill_bundle_artifact(
     )
 
 
+def ignored_junk(directory: Path, name: str, status: os.stat_result) -> bool:
+    """Ignored, untracked OS junk. The caller's no-follow status decides the file type."""
+    if (
+        name not in _common.OS_JUNK_NAMES
+        or is_link_like_status(status)
+        or not stat.S_ISREG(status.st_mode)
+    ):
+        return False
+    try:
+        result = subprocess.run(
+            ["git", "-C", str(directory), "check-ignore", "-q", "--", name],
+            capture_output=True,
+            check=False,
+            env=git_environment(),
+        )
+    except OSError:
+        return False
+    return result.returncode == 0
+
+
 def project_path_inventory(
     project: Path, root: Path
 ) -> tuple[tuple[str, ...], tuple[str, ...]]:
@@ -1001,14 +1028,18 @@ def project_path_inventory(
             posix_relative(current / name, root) for name in linked_directories
         )
         dirnames[:] = [name for name in dirnames if name not in linked_directories]
+        kept = []
         for name in filenames:
             path = current / name
-            relative = posix_relative(path, root)
             status = lstat_evidence(path, missing_ok=False)
+            if ignored_junk(current, name, status):
+                continue
+            kept.append(name)
+            relative = posix_relative(path, root)
             paths.append(relative)
             if is_link_like(path, status) or not stat.S_ISREG(status.st_mode):
                 unsafe_paths.append(relative)
-        if not filenames and not dirnames and current != project:
+        if not kept and not dirnames and current != project:
             paths.append(posix_relative(current, root))
     if not paths:
         try:
@@ -1017,7 +1048,11 @@ def project_path_inventory(
             raise DetectError(
                 f"cannot list project evidence: {project}: {error}"
             ) from error
-        paths = [posix_relative(project / name, root) for name in names]
+        paths = [
+            posix_relative(project / name, root)
+            for name in names
+            if not ignored_junk(project, name, lstat_evidence(project / name, missing_ok=False))
+        ]
     return tuple(sorted(paths)), tuple(sorted(unsafe_paths))
 
 
@@ -1093,7 +1128,7 @@ def classify(repo: Path) -> dict:
         missing_ok=True,
     )
     if (
-        ANCHORED_STATE_CREATE_SUPPORTED
+        STATE_CREATE_SUPPORTED
         and orphan_paths == (f".project/{STATE_TEMP_NAME}",)
         and not unsafe_paths
         and temporary_state_status is not None
@@ -1265,12 +1300,28 @@ def close_file_descriptors(
             pass
 
 
+def project_entries(project_fd: int, project: Path) -> set:
+    """Names in .project without ignored OS junk (Finder may add .DS_Store at any time)."""
+    entries = set(os.listdir(project_fd))
+    for name in entries & _common.OS_JUNK_NAMES:
+        try:
+            status = os.stat(name, dir_fd=project_fd, follow_symlinks=False)
+        except FileNotFoundError:
+            continue  # Keep the name: the caller's comparison then fails closed.
+        if ignored_junk(project, name, status):
+            entries.discard(name)
+    return entries
+
+
 def write_state_anchored(
     root: Path,
     content: str,
     expected_root: os.stat_result,
     expected_project: Optional[os.stat_result],
 ) -> None:
+    if WINDOWS_STATE_CREATE_SUPPORTED:
+        write_state_windows(root, content, expected_root, expected_project)
+        return
     if not ANCHORED_STATE_CREATE_SUPPORTED:
         raise DetectError("anchored no-follow STATE.md creation is unavailable")
     payload = content.encode("utf-8")
@@ -1333,7 +1384,7 @@ def write_state_anchored(
         ):
             raise DetectError(".project changed after classification")
         lock_exclusive(project_fd)
-        entries = set(os.listdir(project_fd))
+        entries = project_entries(project_fd, root / ".project")
         if entries not in (set(), {STATE_TEMP_NAME}):
             raise DetectError(".project changed after classification")
         create = (
@@ -1400,7 +1451,7 @@ def write_state_anchored(
             or not os.path.samestat(created_status, current_state)
         ):
             raise DetectError("temporary STATE.md changed while writing")
-        if set(os.listdir(project_fd)) != {STATE_TEMP_NAME}:
+        if project_entries(project_fd, root / ".project") != {STATE_TEMP_NAME}:
             raise DetectError(".project contents changed while creating STATE.md")
         try:
             os.link(
@@ -1420,7 +1471,7 @@ def write_state_anchored(
         published = os.stat("STATE.md", dir_fd=project_fd, follow_symlinks=False)
         if published.st_nlink != 1 or not os.path.samestat(created_status, published):
             raise DetectError("STATE.md changed while publishing")
-        if set(os.listdir(project_fd)) != {"STATE.md"}:
+        if project_entries(project_fd, root / ".project") != {"STATE.md"}:
             raise DetectError(".project contents changed while publishing STATE.md")
         os.fsync(project_fd)
         closing_state_fd = state_fd
@@ -1448,6 +1499,285 @@ def write_state_anchored(
         close_file_descriptors(state_fd, project_fd, root_fd)
 
 
+# --- Windows anchored creation ------------------------------------------------
+# Windows has no dir_fd, O_NOFOLLOW, or O_DIRECTORY. Handles give the same
+# guarantee (docs/adr/0004-windows-anchored-state.md):
+# - each directory is opened without following a reparse point and held
+#   without FILE_SHARE_DELETE, so it cannot be renamed or replaced while held;
+# - children are opened relative to the held parent handle (NtCreateFile with
+#   a RootDirectory), so no path is resolved again after it was checked;
+# - STATE.md is published by renaming the temporary file's own handle without
+#   replacing an existing name, and rollback deletes through that handle.
+
+_FILE_LIST_DIRECTORY = 0x0001
+_FILE_TRAVERSE = 0x0020
+_FILE_READ_ATTRIBUTES = 0x0080
+_DELETE = 0x00010000
+_SYNCHRONIZE = 0x00100000
+_GENERIC_WRITE = 0x40000000
+_GENERIC_READ = 0x80000000
+_FILE_SHARE_READ = 0x1
+_FILE_SHARE_WRITE = 0x2
+_OPEN_EXISTING = 3
+_FILE_FLAG_OPEN_REPARSE_POINT = 0x00200000
+_FILE_FLAG_BACKUP_SEMANTICS = 0x02000000
+_FILE_OPEN = 1
+_FILE_CREATE = 2
+_FILE_OPEN_IF = 3
+_FILE_DIRECTORY_FILE = 0x00000001
+_FILE_SYNCHRONOUS_IO_NONALERT = 0x00000020
+_FILE_NON_DIRECTORY_FILE = 0x00000040
+_FILE_OPEN_REPARSE_POINT = 0x00200000
+_OBJ_CASE_INSENSITIVE = 0x00000040
+_FILE_RENAME_INFORMATION = 10
+_FILE_DISPOSITION_INFO = 4
+_DIRECTORY_ACCESS = _FILE_LIST_DIRECTORY | _FILE_TRAVERSE | _FILE_READ_ATTRIBUTES | _SYNCHRONIZE
+# Readers and writers may share a held directory; nobody may delete or rename it.
+_PIN_SHARE = _FILE_SHARE_READ | _FILE_SHARE_WRITE
+
+WINDOWS_STATE_CREATE_SUPPORTED = os.name == "nt"
+STATE_CREATE_SUPPORTED = ANCHORED_STATE_CREATE_SUPPORTED or WINDOWS_STATE_CREATE_SUPPORTED
+
+
+class _WindowsHandles:
+    """kernel32/ntdll calls for the Windows anchored create, bound on first use."""
+
+    def __init__(self) -> None:
+        import ctypes
+        import msvcrt
+        from ctypes import wintypes
+
+        class UnicodeString(ctypes.Structure):
+            _fields_ = [("Length", wintypes.USHORT), ("MaximumLength", wintypes.USHORT),
+                        ("Buffer", wintypes.LPWSTR)]
+
+        class ObjectAttributes(ctypes.Structure):
+            _fields_ = [("Length", wintypes.ULONG), ("RootDirectory", wintypes.HANDLE),
+                        ("ObjectName", ctypes.POINTER(UnicodeString)),
+                        ("Attributes", wintypes.ULONG), ("SecurityDescriptor", ctypes.c_void_p),
+                        ("SecurityQualityOfService", ctypes.c_void_p)]
+
+        class IoStatusBlock(ctypes.Structure):
+            _fields_ = [("Status", ctypes.c_void_p), ("Information", ctypes.c_size_t)]
+
+        self.ctypes, self.wintypes, self.msvcrt = ctypes, wintypes, msvcrt
+        self.UnicodeString, self.ObjectAttributes, self.IoStatusBlock = (
+            UnicodeString, ObjectAttributes, IoStatusBlock)
+        self.kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
+        self.ntdll = ctypes.WinDLL("ntdll")
+        self.kernel32.CreateFileW.restype = wintypes.HANDLE
+        self.kernel32.CreateFileW.argtypes = (
+            wintypes.LPCWSTR, wintypes.DWORD, wintypes.DWORD, ctypes.c_void_p,
+            wintypes.DWORD, wintypes.DWORD, wintypes.HANDLE)
+        self.kernel32.SetFileInformationByHandle.argtypes = (
+            wintypes.HANDLE, ctypes.c_int, ctypes.c_void_p, wintypes.DWORD)
+        self.ntdll.NtCreateFile.restype = ctypes.c_long
+        self.ntdll.NtCreateFile.argtypes = (
+            ctypes.POINTER(wintypes.HANDLE), wintypes.DWORD, ctypes.POINTER(ObjectAttributes),
+            ctypes.POINTER(IoStatusBlock), ctypes.c_void_p, wintypes.ULONG, wintypes.ULONG,
+            wintypes.ULONG, wintypes.ULONG, ctypes.c_void_p, wintypes.ULONG)
+        self.ntdll.RtlNtStatusToDosError.restype = wintypes.ULONG
+        self.ntdll.RtlNtStatusToDosError.argtypes = (ctypes.c_long,)
+        self.ntdll.NtSetInformationFile.restype = ctypes.c_long
+        self.ntdll.NtSetInformationFile.argtypes = (
+            wintypes.HANDLE, ctypes.POINTER(IoStatusBlock), ctypes.c_void_p, wintypes.ULONG,
+            ctypes.c_int)
+
+    def adopt(self, handle: int) -> int:
+        """A CRT descriptor that owns handle, so os.fstat, os.write, and os.close apply."""
+        try:
+            descriptor = self.msvcrt.open_osfhandle(handle, 0)
+        except OSError:
+            self.kernel32.CloseHandle(self.wintypes.HANDLE(handle))
+            raise
+        # The CRT adopts handles in text mode, where os.write turns "\n" into "\r\n".
+        self.msvcrt.setmode(descriptor, os.O_BINARY)
+        return descriptor
+
+    def open_root(self, path: Path) -> int:
+        handle = self.kernel32.CreateFileW(
+            str(path), _DIRECTORY_ACCESS, _PIN_SHARE, None, _OPEN_EXISTING,
+            _FILE_FLAG_BACKUP_SEMANTICS | _FILE_FLAG_OPEN_REPARSE_POINT, None)
+        if handle is None or handle == self.wintypes.HANDLE(-1).value:
+            raise self.ctypes.WinError(self.ctypes.get_last_error())
+        return self.adopt(handle)
+
+    def open_relative(
+        self, parent_fd: int, name: str, access: int, share: int, disposition: int, options: int
+    ) -> int:
+        """Open name inside the directory held by parent_fd, never following a reparse point."""
+        ctypes = self.ctypes
+        buffer = ctypes.create_unicode_buffer(name)
+        length = len(name) * ctypes.sizeof(ctypes.c_wchar)
+        object_name = self.UnicodeString(length, length + ctypes.sizeof(ctypes.c_wchar),
+                                         ctypes.cast(buffer, self.wintypes.LPWSTR))
+        attributes = self.ObjectAttributes(
+            ctypes.sizeof(self.ObjectAttributes), self.msvcrt.get_osfhandle(parent_fd),
+            ctypes.pointer(object_name), _OBJ_CASE_INSENSITIVE, None, None)
+        handle = self.wintypes.HANDLE()
+        status = self.ntdll.NtCreateFile(
+            ctypes.byref(handle), access | _SYNCHRONIZE, ctypes.byref(attributes),
+            ctypes.byref(self.IoStatusBlock()), None, 0, share, disposition,
+            options | _FILE_SYNCHRONOUS_IO_NONALERT | _FILE_OPEN_REPARSE_POINT, None, 0)
+        if status < 0:
+            raise ctypes.WinError(self.ntdll.RtlNtStatusToDosError(status))
+        return self.adopt(handle.value)
+
+    def rename_no_replace(self, fd: int, directory_fd: int, name: str) -> None:
+        """Rename the file held by fd to name inside the directory held by directory_fd.
+
+        The renameat equivalent; fails when name already exists.
+        """
+        ctypes, wintypes = self.ctypes, self.wintypes
+
+        class RenameInformation(ctypes.Structure):
+            _fields_ = [("ReplaceIfExists", wintypes.BOOLEAN), ("RootDirectory", wintypes.HANDLE),
+                        ("FileNameLength", wintypes.ULONG),
+                        ("FileName", wintypes.WCHAR * (len(name) + 1))]
+
+        info = RenameInformation(False, self.msvcrt.get_osfhandle(directory_fd),
+                                 len(name) * ctypes.sizeof(ctypes.c_wchar), name)
+        status = self.ntdll.NtSetInformationFile(
+            self.msvcrt.get_osfhandle(fd), ctypes.byref(self.IoStatusBlock()),
+            ctypes.byref(info), ctypes.sizeof(info), _FILE_RENAME_INFORMATION)
+        if status < 0:
+            raise ctypes.WinError(self.ntdll.RtlNtStatusToDosError(status))
+
+    def delete_on_close(self, fd: int) -> None:
+        """Delete exactly the file held by fd when it closes, whatever its name is now."""
+        ctypes = self.ctypes
+        flag = ctypes.c_ubyte(1)
+        if not self.kernel32.SetFileInformationByHandle(
+                self.msvcrt.get_osfhandle(fd), _FILE_DISPOSITION_INFO,
+                ctypes.byref(flag), ctypes.sizeof(flag)):
+            raise ctypes.WinError(ctypes.get_last_error())
+
+
+def windows_project_entries(project: Path) -> set:
+    """project_entries for a .project held open without delete sharing."""
+    entries = set(os.listdir(project))
+    for name in entries & _common.OS_JUNK_NAMES:
+        try:
+            status = os.stat(project / name, follow_symlinks=False)
+        except FileNotFoundError:
+            continue
+        if ignored_junk(project, name, status):
+            entries.discard(name)
+    return entries
+
+
+def write_state_windows(
+    root: Path,
+    content: str,
+    expected_root: os.stat_result,
+    expected_project: Optional[os.stat_result],
+) -> None:
+    win = _WindowsHandles()
+    payload = content.encode("utf-8")
+    project = root / ".project"
+    root_fd = project_fd = state_fd = None
+    delete_on_failure = False
+    # The same lock pipeline_state takes for this track.
+    with _common.directory_mutex(project):
+        try:
+            try:
+                root_fd = win.open_root(root)
+            except OSError as error:
+                raise DetectError(f"cannot open repo for STATE.md creation: {error}") from error
+            opened_root = os.fstat(root_fd)
+            if (
+                is_link_like(root, opened_root)
+                or not stat.S_ISDIR(opened_root.st_mode)
+                or not os.path.samestat(expected_root, opened_root)
+            ):
+                raise DetectError("repo changed after classification")
+            try:
+                project_fd = win.open_relative(
+                    root_fd, ".project", _DIRECTORY_ACCESS, _PIN_SHARE,
+                    _FILE_CREATE if expected_project is None else _FILE_OPEN,
+                    _FILE_DIRECTORY_FILE)
+            except FileExistsError as error:
+                raise DetectError(".project changed after classification") from error
+            except OSError as error:
+                raise DetectError(f"cannot open .project for STATE.md creation: {error}") from error
+            opened_project = os.fstat(project_fd)
+            if is_link_like(project, opened_project) or not stat.S_ISDIR(opened_project.st_mode):
+                raise DetectError("cannot create state through a non-directory .project")
+            if expected_project is not None and not os.path.samestat(expected_project, opened_project):
+                raise DetectError(".project changed after classification")
+            if windows_project_entries(project) not in (set(), {STATE_TEMP_NAME}):
+                raise DetectError(".project changed after classification")
+            try:
+                # Share mode 0: nothing else may open the temporary file while it is held.
+                state_fd = win.open_relative(
+                    project_fd, STATE_TEMP_NAME, _GENERIC_READ | _GENERIC_WRITE | _DELETE,
+                    0, _FILE_OPEN_IF, _FILE_NON_DIRECTORY_FILE)
+            except OSError as error:
+                raise DetectError(f"cannot reserve temporary STATE.md: {error}") from error
+            created_status = os.fstat(state_fd)
+            if is_link_like(project / STATE_TEMP_NAME, created_status) or not stat.S_ISREG(
+                created_status.st_mode
+            ):
+                raise DetectError("temporary STATE.md is not a regular file")
+            if created_status.st_nlink != 1:
+                raise DetectError("temporary STATE.md has an unexpected link count")
+            delete_on_failure = True
+            if "STATE.md" in os.listdir(project):
+                raise DetectError("STATE.md already exists")
+            os.ftruncate(state_fd, 0)
+            write_all(state_fd, payload)
+            os.fsync(state_fd)
+            current_root = lstat_evidence(root, missing_ok=False)
+            current_project = lstat_evidence(project, missing_ok=False)
+            if (
+                is_link_like(root, current_root)
+                or not os.path.samestat(opened_root, current_root)
+                or is_link_like(project, current_project)
+                or not os.path.samestat(opened_project, current_project)
+            ):
+                raise DetectError("project identity changed while creating STATE.md")
+            current_state = os.fstat(state_fd)
+            if current_state.st_nlink != 1 or not os.path.samestat(created_status, current_state):
+                raise DetectError("temporary STATE.md changed while writing")
+            if windows_project_entries(project) != {STATE_TEMP_NAME}:
+                raise DetectError(".project contents changed while creating STATE.md")
+            try:
+                win.rename_no_replace(state_fd, project_fd, "STATE.md")
+            except OSError as error:
+                if "STATE.md" in os.listdir(project):
+                    raise DetectError("STATE.md already exists") from error
+                raise DetectError(f"cannot publish STATE.md: {error}") from error
+            published = lstat_evidence(project / "STATE.md", missing_ok=False)
+            if (
+                is_link_like(project / "STATE.md", published)
+                or published.st_nlink != 1
+                or not os.path.samestat(created_status, published)
+            ):
+                raise DetectError("STATE.md changed while publishing")
+            if windows_project_entries(project) != {"STATE.md"}:
+                raise DetectError(".project contents changed while publishing STATE.md")
+            delete_on_failure = False
+            closing_state_fd, state_fd = state_fd, None
+            try:
+                os.close(closing_state_fd)
+            except OSError as error:
+                raise DetectError(f"cannot close STATE.md: {error}") from error
+        except BaseException as error:
+            if delete_on_failure and state_fd is not None:
+                try:
+                    win.delete_on_close(state_fd)
+                except OSError as rollback_error:
+                    raise DetectError(
+                        f"cannot roll back STATE.md: {rollback_error}") from error
+            if isinstance(error, DetectError):
+                raise
+            if isinstance(error, OSError):
+                raise DetectError(f"cannot create STATE.md: {error}") from error
+            raise
+        finally:
+            close_file_descriptors(state_fd, project_fd, root_fd)
+
+
 def initialize(
     repo: Path, template: Path, phase: Optional[str] = None, *, require_git: bool = False
 ) -> dict:
@@ -1471,7 +1801,7 @@ def initialize(
     if require_git:
         git = subprocess.run(
             ["git", "-C", str(root), "rev-parse", "--is-inside-work-tree"],
-            env=git_environment(), capture_output=True, text=True, check=False,
+            env=git_environment(), capture_output=True, encoding="utf-8", errors="replace", check=False,
         )
         if git.returncode != 0 or git.stdout.strip() != "true":
             return {**payload, "route": "setup-repository", "wrote_state": False}
@@ -1482,7 +1812,7 @@ def initialize(
         raise DetectError(
             f"initialize phase {phase} does not match verdict {payload['verdict']}"
         )
-    if not ANCHORED_STATE_CREATE_SUPPORTED:
+    if not STATE_CREATE_SUPPORTED:
         payload["wrote_state"] = False
         payload["error"] = "anchored no-follow STATE.md creation is unavailable"
         return payload

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

@@ -16,14 +16,20 @@ from pathlib import Path
 from typing import Iterator, Optional, Sequence
 
 def _load_pipeline_modules():
-    try:
-        import archive_milestone
-        import pipeline_state
-        import _common
+    if __package__:
+        from . import archive_milestone
+        from . import pipeline_state
+        from . import _common
         return _common, archive_milestone, pipeline_state
-    except ModuleNotFoundError as error:
-        if error.name not in {"archive_milestone", "pipeline_state", "_common"}:
-            raise
+    else:
+        try:
+            import archive_milestone
+            import pipeline_state
+            import _common
+            return _common, archive_milestone, pipeline_state
+        except ModuleNotFoundError as error:
+            if error.name not in {"archive_milestone", "pipeline_state", "_common"}:
+                raise
     try:
         from scripts import archive_milestone, pipeline_state, _common
         return _common, archive_milestone, pipeline_state
@@ -111,7 +117,7 @@ def record_count(directory: Path) -> int:
 def validate_or_empty(directory: Path) -> None:
     if directory.is_symlink() or not directory.is_dir():
         raise DiscussionError("discussion records must be a real directory")
-    if sorted(path.name for path in directory.iterdir()) != sorted(FILES):
+    if sorted(path.name for path in directory.iterdir() if not _common.is_ignored_junk(path)) != sorted(FILES):
         raise DiscussionError("discussion directory must contain exactly DIALOGUE.md and ANSWERS.md")
     if record_count(directory) == 0:
         if "### D" in (directory / "DIALOGUE.md").read_text(encoding="utf-8"):
@@ -170,7 +176,7 @@ def validate_contents(project: Path, files: dict) -> None:
     staging.mkdir()
     try:
         for name in FILES:
-            (staging / name).write_text(files[name], encoding="utf-8")
+            (staging / name).write_bytes(files[name].encode("utf-8"))
         validate_or_empty(staging)
     finally:
         shutil.rmtree(staging)
@@ -187,11 +193,11 @@ def initialize_records(discussion: Path, dialogue_template: Path, answers_templa
         shutil.rmtree(staging)
     staging.mkdir()
     try:
-        (staging / "DIALOGUE.md").write_text(
-            template_header(dialogue_template, "### D001"), encoding="utf-8"
+        (staging / "DIALOGUE.md").write_bytes(
+            template_header(dialogue_template, "### D001").encode("utf-8")
         )
-        (staging / "ANSWERS.md").write_text(
-            template_header(answers_template, "## Answer A001"), encoding="utf-8"
+        (staging / "ANSWERS.md").write_bytes(
+            template_header(answers_template, "## Answer A001").encode("utf-8")
         )
         os.replace(staging, discussion)
     finally:

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

@@ -14,12 +14,16 @@ from datetime import date
 from pathlib import Path, PurePosixPath
 from typing import Optional, Sequence
 
-try:
-    from pipeline_state import PipelineState
-    import _common
-except ImportError:  # pragma: no cover - package import used by tests
-    from scripts.pipeline_state import PipelineState
-    from scripts import _common
+if __package__:
+    from .pipeline_state import PipelineState
+    from . import _common
+else:
+    try:
+        from pipeline_state import PipelineState
+        import _common
+    except ImportError:  # pragma: no cover - package import used by tests
+        from scripts.pipeline_state import PipelineState
+        from scripts import _common
 
 
 atomic_replace = _common.atomic_replace
@@ -105,7 +109,7 @@ def validate_discussion_directory(
 ) -> None:
     if directory.is_symlink() or not directory.is_dir():
         raise ArchiveError("discussion archive must be a real directory")
-    entries = sorted(path.name for path in directory.iterdir())
+    entries = sorted(path.name for path in directory.iterdir() if not _common.is_ignored_junk(path))
     if entries != sorted(DISCUSSION_FILES):
         raise ArchiveError("discussion archive must contain exactly DIALOGUE.md and ANSWERS.md")
     dialogue, answers = (directory / name for name in DISCUSSION_FILES)
@@ -490,10 +494,13 @@ def archived_intent_criteria(archive: Path) -> dict[int, str]:
     if not archive_milestone.is_real_file(intent):
         raise ArchiveError("archived intent must be a real INTENT.md file")
     text = HTML_COMMENT_PATTERN.sub("", intent.read_text(encoding="utf-8"))
-    try:
-        import check_handoffs
-    except ImportError:
-        from scripts import check_handoffs
+    if __package__:
+        from . import check_handoffs
+    else:
+        try:
+            import check_handoffs
+        except ImportError:
+            from scripts import check_handoffs
     try:
         criteria = check_handoffs._success_criteria(text)
     except check_handoffs.HandoffError as error:
@@ -502,10 +509,13 @@ def archived_intent_criteria(archive: Path) -> dict[int, str]:
 
 
 def parse_final_review(archive: Path) -> tuple:
-    try:
-        import check_handoffs
-    except ImportError:  # pragma: no cover - package import used by tests
-        from scripts import check_handoffs
+    if __package__:
+        from . import check_handoffs
+    else:
+        try:
+            import check_handoffs
+        except ImportError:  # pragma: no cover - package import used by tests
+            from scripts import check_handoffs
 
     final = archive / "review" / "FINAL.md"
     if not archive_milestone.is_real_file(final):
@@ -597,8 +607,29 @@ def parse_final_review(archive: Path) -> tuple:
     return reviewed_head.lower(), criteria
 
 
+def _member_heads(text: str, source: str) -> dict:
+    if __package__:
+        from . import check_handoffs
+    else:
+        try:
+            import check_handoffs
+        except ImportError:  # pragma: no cover - package import used by tests
+            from scripts import check_handoffs
+    try:
+        return check_handoffs.member_reviewed_heads(text, source)
+    except check_handoffs.HandoffError as error:
+        raise ArchiveError(str(error)) from error
+
+
 def validate_gap_reviews(archive: Path, reviewed_head: str) -> None:
     review = archive / "review"
+    member_heads = _member_heads((review / "FINAL.md").read_text(encoding="utf-8"), "FINAL.md")
+    lock = archive / "build" / "members.json"
+    locked = [item["name"] for item in json.loads(lock.read_text(encoding="utf-8"))["members"]] if lock.is_file() else []
+    if sorted(member_heads) != sorted(locked):
+        raise ArchiveError(
+            "FINAL.md Member reviewed HEAD lines must name each locked member: " + (", ".join(locked) or "none")
+        )
     candidates = sorted(path for path in review.iterdir() if path.name.startswith("final-gap-"))
     if not candidates:
         raise ArchiveError("final review requires at least one final-gap-N.md artifact")
@@ -626,6 +657,8 @@ def validate_gap_reviews(archive: Path, reviewed_head: str) -> None:
         gap_head = completed_field(lines, "Reviewed HEAD:", path.name).lower()
         if gap_head != reviewed_head:
             raise ArchiveError(f"{path.name} Reviewed HEAD does not match FINAL.md")
+        if _member_heads("\n".join(lines), path.name) != member_heads:
+            raise ArchiveError(f"{path.name} Member reviewed HEAD lines do not match FINAL.md")
         if completed_field(lines, "Gap verdict:", path.name) != "pass":
             raise ArchiveError(f"{path.name} gap review did not pass")
         risk = completed_field(lines, "Risk:", path.name)
@@ -655,10 +688,13 @@ def validate_gap_reviews(archive: Path, reviewed_head: str) -> None:
 
 
 def meaningful_review_evidence(lines: Sequence[str], marker: str, task_text: str = "") -> bool:
-    try:
-        from check_handoffs import task_review_observation
-    except ImportError:  # pragma: no cover - package import used by tests
-        from scripts.check_handoffs import task_review_observation
+    if __package__:
+        from .check_handoffs import task_review_observation
+    else:
+        try:
+            from check_handoffs import task_review_observation
+        except ImportError:  # pragma: no cover - package import used by tests
+            from scripts.check_handoffs import task_review_observation
 
     prefix = f"- {marker} "
     evidence = []
@@ -1071,8 +1107,17 @@ def archive_file_inventory(archive: Path) -> Sequence[str]:
     for path in archive.rglob("*"):
         if path.is_symlink():
             raise ArchiveError(f"archive contents must not be symlinks: {path}")
-        if path.is_file() and path.name != "MANIFEST.md":
-            contents.append(path.relative_to(archive).as_posix())
+        if not path.is_file() or path.name == "MANIFEST.md":
+            continue
+        relative = path.relative_to(archive)
+        if _common.is_ignored_junk(path):
+            if len(relative.parts) == 1:
+                continue
+            original = archive.parent.parent / relative
+            project = archive.parent.parent.parent
+            if run_git(project, "check-ignore", "-q", "--", original.relative_to(project).as_posix()).returncode == 0:
+                continue
+        contents.append(relative.as_posix())
     return sorted(contents)