@opengsd/gsd-path 1.3.1 → 1.5.0

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

@@ -17,12 +17,15 @@ from datetime import date
 from pathlib import Path, PurePosixPath
 from typing import Mapping, Optional, Sequence
 
-try:
-    from isolation import IsolationError, checkpoint as isolation_checkpoint, require_commit, require_full_sha, PROJECT_ENTRIES
-except ModuleNotFoundError as error:  # pragma: no cover - package imports used by tests
-    if error.name != "isolation":
-        raise
-    from scripts.isolation import IsolationError, checkpoint as isolation_checkpoint, require_commit, require_full_sha, PROJECT_ENTRIES
+if __package__:
+    from .isolation import IsolationError, checkpoint as isolation_checkpoint, PROJECT_ENTRIES
+else:
+    try:
+        from isolation import IsolationError, checkpoint as isolation_checkpoint, PROJECT_ENTRIES
+    except ModuleNotFoundError as error:  # pragma: no cover - package imports used by tests
+        if error.name != "isolation":
+            raise
+        from scripts.isolation import IsolationError, checkpoint as isolation_checkpoint, PROJECT_ENTRIES
 
 
 if __package__:
@@ -66,6 +69,11 @@ def _sha256(content: str) -> str:
     return hashlib.sha256(content.encode("utf-8")).hexdigest()
 
 
+def _is_junk_file(path: Path) -> bool:
+    # Drift digests skip OS junk by name: Finder rewrites it whatever its ignore status.
+    return path.name in pipeline_state._common.OS_JUNK_NAMES and path.is_file() and not path.is_symlink()
+
+
 def _tree_digest(path: Path, excluded: Sequence[str] = ()) -> str:
     if path.is_symlink() or not path.is_dir():
         raise PipelineStateError(f"promotion path must be a real directory: {path}")
@@ -74,7 +82,7 @@ def _tree_digest(path: Path, excluded: Sequence[str] = ()) -> str:
         if child.is_symlink():
             raise PipelineStateError(f"promotion path contains a symlink: {child}")
         relative = child.relative_to(path).as_posix()
-        if PurePosixPath(relative).parts[0] in excluded:
+        if PurePosixPath(relative).parts[0] in excluded or _is_junk_file(child):
             continue
         if child.is_dir():
             digest.update(f"d\0{relative}\0".encode())
@@ -87,15 +95,15 @@ def _tree_digest(path: Path, excluded: Sequence[str] = ()) -> str:
 
 
 def _checkpoint_artifact_digest(project: Path, mutable_paths: set[str]) -> str:
-    """Hash every approval artifact except the helper-owned metadata files."""
+    """Hash approval artifacts except helper-owned metadata and OS junk."""
     digest = hashlib.sha256()
     for child in sorted(project.rglob("*")):
         if child.is_symlink():
             raise PipelineStateError(f"checkpoint path contains a symlink: {child}")
         relative = child.relative_to(project).as_posix()
-        # Unsupported entries (OS junk) are refused by the checkpoint itself; leaving them
-        # out lets a refused approval resume after the owner removes them.
-        if relative in mutable_paths or relative.split("/", 1)[0] not in PROJECT_ENTRIES:
+        # Finder can rewrite OS junk during approval; it must not cause artifact drift.
+        if (relative in mutable_paths or relative.split("/", 1)[0] not in PROJECT_ENTRIES
+                or _is_junk_file(child)):
             continue
         if child.is_dir():
             digest.update(f"d\0{relative}\0".encode())
@@ -333,11 +341,7 @@ def _converge_checkpoint_file(path: Path, before: str, after: str, label: str) -
 
 def _unlink_checkpoint_journal(path: Path) -> None:
     path.unlink()
-    descriptor = os.open(path.parent, os.O_RDONLY)
-    try:
-        os.fsync(descriptor)
-    finally:
-        os.close(descriptor)
+    pipeline_state._common.fsync_directory(path.parent)
 
 
 def _resume_checkpoint_locked(
@@ -439,41 +443,85 @@ def _validate_plan_briefs(repo: Path, kind: str, project_dir: str) -> None:
     if head.returncode != 0:
         # Pre-Git approval defers base-dependent checks to build.
         return
+    if __package__:
+        from .check_task_briefs import BriefError, _member_bases, plan_validation_bases, validate_task_briefs
+    else:
+        try:
+            from check_task_briefs import BriefError, _member_bases, plan_validation_bases, validate_task_briefs
+        except ModuleNotFoundError as error:  # pragma: no cover - package imports
+            if error.name != "check_task_briefs":
+                raise
+            from scripts.check_task_briefs import BriefError, _member_bases, plan_validation_bases, validate_task_briefs
+    if __package__:
+        from . import check_handoffs
+    else:
+        try:
+            import check_handoffs
+        except ModuleNotFoundError as error:
+            if error.name != "check_handoffs":
+                raise
+            from scripts import check_handoffs
     try:
-        from check_task_briefs import BriefError, validate_task_briefs
-    except ModuleNotFoundError as error:  # pragma: no cover - package imports
-        if error.name != "check_task_briefs":
-            raise
-        from scripts.check_task_briefs import BriefError, validate_task_briefs
-    try:
-        import check_handoffs
-    except ModuleNotFoundError as error:
-        if error.name != "check_handoffs":
-            raise
-        from scripts import check_handoffs
-    try:
-        tasks, dependency_files = check_handoffs.plan_brief_inputs(repo, project_dir)
-        landed_bases = {}
-        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")
-            recorded_base = check_handoffs._task_scalar(text, task_id, "base")
-            try:
-                landed_bases[task_id] = require_commit(repo, require_full_sha(recorded_base))
-            except IsolationError as error:
-                raise BriefError(f"{task_id} landed task has invalid historical base: {error}") from error
-            dependency_files[task_id] = set()
+        member_base = _member_bases(repo)
+        tasks, dependency_files, landed_bases = plan_validation_bases(
+            repo, project_dir, member_base, initial=True
+        )
         validate_task_briefs(
             repo, head.stdout.strip(), f"{project_dir}/tasks",
             dependency_files=dependency_files, landed_bases=landed_bases,
+            member_base=member_base,
         )
+        if project_dir == ".project/next":
+            # Promotion checks lookahead member tasks from the bases their briefs were checked at.
+            named = {
+                str(check_handoffs._strict_frontmatter(text, task_id).get("repo"))
+                for task_id, text in tasks.items()
+                if check_handoffs._strict_frontmatter(text, task_id).get("repo")
+                and check_handoffs._task_scalar(text, task_id, "status") != "done"
+            }
+            if named:
+                bases = {name: member_base(name)[1] for name in sorted(named)}
+                milestone = pipeline_state.load_state(repo, project_dir)[0].milestone
+                path = _lookahead_member_bases_path(repo, str(milestone))
+                path.parent.mkdir(parents=True, exist_ok=True)
+                pipeline_state._common.atomic_write(path, json.dumps(
+                    {"schema": LOOKAHEAD_MEMBER_BASES_SCHEMA, "milestone": milestone, "bases": bases},
+                    indent=2, sort_keys=True) + "\n")
     except (BriefError, check_handoffs.HandoffError) as error:
         raise PipelineStateError(f"task brief validation failed: {error}") from error
 
 
+LOOKAHEAD_MEMBER_BASES_SCHEMA = "gsd-path/lookahead-member-bases/v1"
+
+
+def _lookahead_member_bases_path(repo: Path, milestone: str) -> Path:
+    common = pipeline_state._run_git(repo, "rev-parse", "--path-format=absolute", "--git-common-dir").stdout.strip()
+    return Path(common) / "gsd-path" / "lookahead-member-bases" / f"{milestone}.json"
+
+
+def _lookahead_member_bases(repo: Path, milestone: str) -> Optional[dict]:
+    path = _lookahead_member_bases_path(repo, milestone)
+    if not path.is_file():
+        return None
+    value = json.loads(path.read_text(encoding="utf-8"))
+    if value.get("schema") != LOOKAHEAD_MEMBER_BASES_SCHEMA or value.get("milestone") != milestone:
+        return None
+    return value.get("bases")
+
+
+def _shipped_member_merges(repo: Path, landing: str) -> dict:
+    """Member merges named by the ship commit the integration landing merged."""
+    if __package__:
+        from .pipeline_git import ship_member_rows
+    else:
+        from pipeline_git import ship_member_rows
+    ship = pipeline_state._run_git(repo, "rev-parse", "--verify", "--quiet", f"{landing}^2", check=False)
+    if ship.returncode != 0:
+        return {}
+    message = pipeline_state._run_git(repo, "show", "-s", "--format=%B", ship.stdout.strip()).stdout
+    return {row["name"]: row["merge"] for row in ship_member_rows(message)}
+
+
 def checkpoint_approval(
     repo: Path,
     kind: str,
@@ -1027,6 +1075,46 @@ def _classify_plan_drift(
         }
     approved = _approved_task_contracts(repo, checkpoint)
     current = _task_contracts_at(repo, revision)
+    if __package__:
+        from . import check_handoffs
+    else:
+        import check_handoffs
+    # Member task paths live in member repos: compare each member from the base its brief
+    # was checked at to the member merge the shipped milestone made (both fixed commits).
+    task_repos = {
+        task_id: str(check_handoffs._strict_frontmatter(contract.text, contract.path).get("repo") or "")
+        for task_id, contract in approved.items()
+    }
+    active_member_tasks = {
+        task_id for task_id, name in task_repos.items()
+        if name and check_handoffs._task_scalar(approved[task_id].text, task_id, "status") != "done"
+    }
+    active_members = {task_repos[task_id] for task_id in active_member_tasks}
+    member_changes: dict[str, list] = {}
+    if active_members:
+        bases = _lookahead_member_bases(repo, str(state.milestone)) or {}
+        if any(name not in bases for name in active_members):
+            return {
+                "class": "unverifiable",
+                "checkpoint": checkpoint,
+                "task_ids": [],
+                "changed_paths": [],
+                "contract_paths": [],
+                "member_tasks": True,
+                "reason": "member bases were not recorded at plan approval",
+            }
+        if __package__:
+            from . import members
+        else:
+            import members
+        checkouts = {item["name"]: Path(item["checkout"]) for item in members.read_members(repo)}
+        merges = _shipped_member_merges(repo, landing or revision)
+        for name in active_members:
+            member_changes[name] = [
+                item for item in pipeline_state._run_git(
+                    checkouts[name], "diff", "--no-renames", "--name-only", "-z", bases[name], merges[name]
+                ).stdout.split("\0") if item
+            ] if name in merges else []
 
     contract_paths: set[str] = set()
     flagged_ids: set[str] = set()
@@ -1050,9 +1138,12 @@ def _classify_plan_drift(
 
     product_paths: set[str] = set()
     for task_id, contract in approved.items():
+        member = task_repos.get(task_id)
+        if member and task_id not in active_member_tasks:
+            continue
         matches = sorted(
-            changed_path
-            for changed_path in changed
+            (f"{member}:{changed_path}" if member else changed_path)
+            for changed_path in (member_changes[member] if member else changed)
             if any(
                 changed_path == path
                 or changed_path.startswith(f"{path.rstrip('/')}/")

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

@@ -82,6 +82,8 @@ def _promotion_event(
         if isinstance(task_ids, list) and task_ids:
             return f"{prefix}; plan drift flagged tasks {', '.join(task_ids)}"
         return f"{prefix}; plan contract changed after approval"
+    if drift_class == "unverifiable" and drift.get("member_tasks"):
+        return f"{prefix}; plan drift unverifiable because member bases were not recorded at plan approval"
     if drift_class == "unverifiable":
         return f"{prefix}; plan drift unverifiable because approval checkpoint is missing"
     return prefix

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

@@ -13,10 +13,34 @@ import os
 import tempfile
 from pathlib import Path
 
-try:
-    import _common
-except ImportError:
-    from scripts import _common
+if __package__:
+    from . import _common
+else:
+    try:
+        import _common
+    except ImportError:
+        from scripts import _common
+
+
+def _worktree_list_porcelain(primary: Path) -> tuple[str, bool]:
+    try:
+        if __package__:
+            from . import pipeline_git as pg
+        else:
+            from scripts import pipeline_git as pg
+    except ImportError:
+        try:
+            import pipeline_git as pg
+        except ImportError:
+            pg = None
+    if pg is not None:
+        return pg.worktree_list_porcelain(primary)
+    try:
+        output = _git(primary, "worktree", "list", "--porcelain", "-z")
+        return output, True
+    except ValueError:
+        output = _git(primary, "worktree", "list", "--porcelain")
+        return output, False
 
 
 def _git(primary: Path, *args: str) -> str:
@@ -27,7 +51,10 @@ def _git(primary: Path, *args: str) -> str:
 
 
 def _identity(path: Path) -> str:
-    return hashlib.sha256(os.fsencode(path)).hexdigest()
+    digest = hashlib.sha256(os.fsencode(path)).hexdigest()
+    # Two identities nest in every managed path; full digests would use about
+    # 130 of Windows' 260-character MAX_PATH before any repository content.
+    return digest[:16] if os.name == "nt" else digest
 
 
 def _workspace(primary: Path, pin: bool) -> Path:
@@ -65,7 +92,7 @@ def _workspace(primary: Path, pin: bool) -> Path:
         receipt.parent.mkdir(parents=True, exist_ok=True)
         fd, temporary = tempfile.mkstemp(dir=receipt.parent)
         try:
-            with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            with os.fdopen(fd, "w", encoding="utf-8", newline="\n") as handle:
                 json.dump({"primary": str(primary), "root": str(workspace)}, handle)
             try:
                 os.link(temporary, receipt)
@@ -76,17 +103,52 @@ def _workspace(primary: Path, pin: bool) -> Path:
     return workspace
 
 
+def release_workspace(primary: Path) -> bool:
+    """Forget the pinned placement receipt once no linked worktrees remain.
+
+    Lets GSD_PATH_WORKTREE_ROOT (or a new default) apply again at the next
+    milestone's first allocation. Returns True when a receipt was removed;
+    any remaining linked worktree (including one only still registered) keeps
+    the pin.
+    """
+    primary = primary.resolve()
+    common = Path(_git(primary, "rev-parse", "--git-common-dir"))
+    common = (primary / common).resolve()
+    receipt = common / "gsd-path" / "workspaces" / f"{_identity(primary)}.json"
+    if not receipt.is_file():
+        return False
+    output, nul_separated = _worktree_list_porcelain(primary)
+    records = output.split("\0\0") if nul_separated else [
+        block for block in output.strip().split("\n\n") if block.strip()
+    ]
+    for record in records:
+        fields = record.split("\0") if nul_separated else record.splitlines()
+        for field in fields:
+            if field.startswith("worktree ") and Path(field[len("worktree "):]).resolve() != primary:
+                return False
+    receipt.unlink()
+    return True
+
+
 def worktree_path(primary: Path, kind: str, name: str, *, pin: bool = False) -> Path:
     primary = primary.resolve()
-    if kind not in {"task", "verify", "integrate"} or not name or Path(name).name != name or name in {".", ".."}:
+    if kind not in {"task", "verify", "integrate", "bound"} or not name or Path(name).name != name or name in {".", ".."}:
         raise ValueError("invalid managed worktree kind or name")
+    if kind == "bound":
+        return _workspace(primary, pin) / kind / name
     legacy = (primary.parent / f".{primary.name}-gsd-path-integrate-{name}"
               if kind == "integrate" else primary.parent / f"{primary.name}.gsd-path" / kind / name)
     branch = f"refs/heads/gsd-path-{kind}/{name}"
-    records = _git(primary, "worktree", "list", "--porcelain", "-z").split("\0\0")
+    output, nul_separated = _worktree_list_porcelain(primary)
+    if nul_separated:
+        records = output.split("\0\0")
+    else:
+        records = [block for block in output.strip().split("\n\n") if block.strip()]
     for record in records:
-        fields = record.split("\0")
-        if f"worktree {legacy}" in fields and f"branch {branch}" in fields:
+        fields = record.split("\0") if nul_separated else record.splitlines()
+        # Compare as paths: git prints forward slashes on Windows.
+        worktrees = [Path(field[len("worktree "):]) for field in fields if field.startswith("worktree ")]
+        if legacy in worktrees and f"branch {branch}" in fields:
             return legacy
     # Keep collision checks and missing-directory recovery at the old location.
     if os.path.lexists(legacy):

package/skills/gsd-path-define/SKILL.md

@@ -3,7 +3,8 @@ name: gsd-path-define
 description: Define and approve project or milestone intent through an interview or milestone confirmation, writing .project/CHARTER.md or .project/intent/INTENT.md. Use only when the user explicitly invokes $gsd-path-define or an active $gsd-path router explicitly routes to this phase.
 ---
 
-Before executing project helpers, read [runtime selection](references/runtime-selection.md).
+Before executing project helpers, read [runtime selection](references/runtime-selection.md)
+and [operating rules](references/operating-rules.md).
 
 # GSD Path Define Phase
 
@@ -99,6 +100,10 @@ Obtain a confident answer in every area before finishing:
    give every named surface at least one success criterion observable
    there. A criterion satisfied by a passing test alone does not cover a
    surface.
+9. **Edges and prohibitions** — once the success criteria are drafted, run
+   the [spec-reach probes](references/spec-probes.md): every applicable edge
+   and every kept prohibition gets the user's ruling in INTENT.md
+   `## Edge coverage` and `## Prohibitions`.
 
 ## Program mode
 
@@ -148,7 +153,10 @@ State ownership. There is no re-interview of charter or roadmap scope:
    `Lane: milestone`, `Surfaces:` copied verbatim from the entry, and
    `Review panel:` copied from CHARTER.md (default
    the configured preference when CHARTER omits it). The confirmation may override the copied
-   panel value; do not invent `detected` or a named list. When brownfield,
+   panel value; do not invent `detected` or a named list. Run the
+   [spec-reach probes](references/spec-probes.md) over the derived criteria
+   and draft `## Edge coverage` and `## Prohibitions` with recommended
+   rulings. When brownfield,
    fill `## Current state` from the map, record doc-vs-code rulings as in
    Brownfield mode, and add protected existing behavior under Scope out.
    Write Ground truth paths from the track root: `.project` normally, or
@@ -156,7 +164,9 @@ State ownership. There is no re-interview of charter or roadmap scope:
    active `research/` paths.
 3. Present one confirmation, not an interview: playback the derivation (and
    brownfield ground truth when present), link the resolved absolute INTENT.md
-   path, and ask approve or adjust. A requested change that contradicts the
+   path, and ask approve or adjust. The confirmation lists each proposed edge
+   and prohibition ruling for the user to accept or change; it never rules on
+   them silently. A requested change that contradicts the
    charter or the resolved roadmap entry is a scope change — this phase never
    edits the roadmap; surface it to the user for a `$gsd-path-roadmap` re-slice
    at the next milestone boundary.
@@ -253,7 +263,15 @@ question. The rules change for every primary mode:
    the brownfield map already established. Milestone mode skips this step.
 5. Stop when coverage is complete or the user says `enough`. Record remaining
    uncertainty under `## Open questions` with `RESEARCH` or `NEEDS-USER`.
-6. Classify the proposed milestone lane before writing the approval draft.
+   `enough` does not skip the next step.
+6. In standard mode, run the [spec-reach probes](references/spec-probes.md)
+   over the drafted success criteria: one question round for edges, then one
+   for kept prohibitions, each with a recommended ruling first. A ruling
+   observable where the user sees the work becomes or amends a success
+   criterion; write every ruling into `## Edge coverage` and
+   `## Prohibitions`. Program mode skips this step (each milestone runs it
+   in milestone mode); milestone mode runs it inside its confirmation.
+7. Classify the proposed milestone lane before writing the approval draft.
    Milestone mode keeps `Lane: milestone` and skips this classification.
    Program mode writes CHARTER.md instead of INTENT.md. Otherwise choose
    `quick` when scope fits at most two deliverable-sized tasks (project
@@ -274,6 +292,11 @@ question. The rules change for every primary mode:
 ## Output contract
 
 At approval, retain the already reviewed `Lane:` value and its one-line reason.
+Before every approval question on INTENT.md, run the bundled `python3
+<absolute-bundled-script> intent --repo <absolute-root>` helper
+(`scripts/check_handoffs.py`, plus `--project-dir .project/next` in
+lookahead). It checks the success criteria, Surfaces, and both probe tables;
+fix a failure in the draft before asking. It approves nothing.
 Before presenting an approval draft without a CHARTER or explicit panel choice,
 read `settings.review_panel.value` from the selected runtime's `path_config.py
 show --repo <absolute-root>` (bundle for legacy projects; off for older selected
@@ -281,6 +304,12 @@ runtimes without config support). Include that preference in the draft.
 Retain `Review panel:` as reviewed: the CHARTER copy, the explicit user choice,
 or the configured future preference. Quick lane keeps the panel off.
 
+When the active router recorded an `intent` pre-approval grant and the draft
+needs no answer from the user, run the router's `workflow_run.py preauthorize
+--kind intent` before asking. On `complete`, present Outcome and Review, say
+the owner's pre-approval passed this gate, and continue as approved. On
+`blocked`, ask as usual.
+
 After approval, finalize `.project/intent/INTENT.md` and run
 `pipeline_state.py transition` with expected `define/active`, the exact
 current milestone/branch/archive values, event `milestone intent approved`,
@@ -295,5 +324,8 @@ Use the executable phase handoff in AGENTS.md for the next action.
 - In brownfield mode, state mapped facts for correction; never re-ask them.
 - Treat solution-shaped problems as hypotheses and uncover the underlying pain.
 - Preserve vetoes and corrections verbatim.
+- Never rule on an edge's behavior or a prohibition yourself; recommend,
+  then record the user's ruling. An edge the user has not ruled on is a
+  required answer, including under pre-approval.
 - Wrap up when every coverage-checklist area is answered or the user signals
   done, and tag remaining gaps.