@opengsd/gsd-path 1.3.0 → 1.4.0

package/skills/gsd-path-research/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"
@@ -183,10 +186,47 @@ def _verify_tokens(block: str) -> List[str]:
     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 +238,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 +286,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 "
@@ -255,7 +304,7 @@ def _lint_task(
                 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 _base_exists(git_root, base, token)
             ):
                 problems.append(f"## {name} names a path missing at the layer base: {token}")
 
@@ -267,7 +316,7 @@ def _lint_task(
         else:
             for token in _verify_tokens(block.group("block")):
                 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 _base_exists(git_root, base, token):
                     problems.append(f"## Verify names a path missing at the layer base: {token}")
 
     contract = None
@@ -284,6 +333,7 @@ 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.
 
@@ -305,9 +355,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:

package/skills/gsd-path-research/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-research/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: