@opengsd/gsd-path 1.0.0 → 1.2.0

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

@@ -4,6 +4,11 @@
 
 from __future__ import annotations
 
+import sys
+
+# Runtime helpers must not modify their immutable installation.
+sys.dont_write_bytecode = True
+
 import json
 import re
 import shutil
@@ -11,6 +16,31 @@ from pathlib import Path, PurePosixPath
 from typing import Mapping, Optional
 
 
+if __package__:  # imported as scripts.state_promote
+    from . import pipeline_state, state_checkpoint
+    from .pipeline_state import (
+        NULL,
+        PROMOTION_RESIDUAL,
+        PROMOTION_SCHEMA,
+        PROMOTION_TRACKS,
+        SLUG_RE,
+        PipelineState,
+        PipelineStateError,
+    )
+else:  # standalone script or sibling import
+    import pipeline_state
+    import state_checkpoint
+    from pipeline_state import (
+        NULL,
+        PROMOTION_RESIDUAL,
+        PROMOTION_SCHEMA,
+        PROMOTION_TRACKS,
+        SLUG_RE,
+        PipelineState,
+        PipelineStateError,
+    )
+
+
 def _render_roadmap(
     text: str,
     previous_milestone: str,
@@ -243,9 +273,9 @@ def _completed_promotion(
     if _head_with_exact_message(repo, subject, fields) != head:
         raise PipelineStateError("completed promotion has the wrong commit message")
 
-    active_text = pipeline_state._git_text_at(repo, base, ".project/STATE.md")
-    next_text = pipeline_state._git_text_at(repo, base, ".project/next/STATE.md")
-    roadmap_text = pipeline_state._git_text_at(repo, base, ".project/ROADMAP.md")
+    active_text = state_checkpoint._git_text_at(repo, base, ".project/STATE.md")
+    next_text = state_checkpoint._git_text_at(repo, base, ".project/next/STATE.md")
+    roadmap_text = state_checkpoint._git_text_at(repo, base, ".project/ROADMAP.md")
     if active_text is None or next_text is None or roadmap_text is None:
         raise PipelineStateError("promotion parent is missing required metadata")
     active_state = pipeline_state._state_from_text(active_text, "promotion parent STATE.md")
@@ -265,7 +295,7 @@ def _completed_promotion(
         )
 
     _promotion_tree_mapping(repo, base, head)
-    drift = pipeline_state._classify_plan_drift(repo, next_state, base, landing)
+    drift = state_checkpoint._classify_plan_drift(repo, next_state, base, landing)
     expected_roadmap = _render_roadmap(
         roadmap_text,
         active_state.milestone,
@@ -273,11 +303,11 @@ def _completed_promotion(
         branch,
         landing,
     )
-    current_roadmap = pipeline_state._git_text_at(repo, head, ".project/ROADMAP.md")
+    current_roadmap = state_checkpoint._git_text_at(repo, head, ".project/ROADMAP.md")
     if current_roadmap != expected_roadmap:
         raise PipelineStateError("completed promotion has invalid ROADMAP.md")
 
-    current_state = pipeline_state._git_text_at(repo, head, ".project/STATE.md")
+    current_state = state_checkpoint._git_text_at(repo, head, ".project/STATE.md")
     if current_state is None:
         raise PipelineStateError("completed promotion has no STATE.md")
     event = re.escape(_promotion_event(drift, branch, landing, base))
@@ -438,10 +468,10 @@ def _prepare_promotion(
         if source.exists() or source.is_symlink():
             if destination.exists() or destination.is_symlink():
                 raise PipelineStateError(f"promotion destination already exists: {destination}")
-            tracks[name] = pipeline_state._tree_digest(source)
+            tracks[name] = state_checkpoint._tree_digest(source)
     if not tracks:
         raise PipelineStateError("lookahead track has no promotable artifacts")
-    drift = pipeline_state._classify_plan_drift(repo, next_state, base, landing)
+    drift = state_checkpoint._classify_plan_drift(repo, next_state, base, landing)
     roadmap_path = project / "ROADMAP.md"
     roadmap_text = pipeline_state._read_real_file(roadmap_path, "ROADMAP.md")
     target_state = _promotion_state(
@@ -464,10 +494,10 @@ def _prepare_promotion(
         "landing": landing,
         "base": base,
         "tracks": tracks,
-        "residual_sha256": pipeline_state._tree_digest(next_root, tuple(tracks)),
-        "next_state_sha256": pipeline_state._sha256(next_text),
-        "active_state_sha256": pipeline_state._sha256(active_text),
-        "roadmap_sha256": pipeline_state._sha256(roadmap_text),
+        "residual_sha256": state_checkpoint._tree_digest(next_root, tuple(tracks)),
+        "next_state_sha256": state_checkpoint._sha256(next_text),
+        "active_state_sha256": state_checkpoint._sha256(active_text),
+        "roadmap_sha256": state_checkpoint._sha256(roadmap_text),
         "target_state": target_state,
         "target_roadmap": target_roadmap,
         "drift": drift,
@@ -521,7 +551,7 @@ def _resume_track_moves(project: Path, journal: dict[str, object], path: Path) -
         if not source_exists and not destination_exists:
             raise PipelineStateError(f"promotion lost both source and destination: {name}")
         candidate = source if source_exists else destination
-        if pipeline_state._tree_digest(candidate) != expected_digest:
+        if state_checkpoint._tree_digest(candidate) != expected_digest:
             raise PipelineStateError(f"promotion track drifted: {name}")
         if source_exists:
             source.rename(destination)
@@ -542,7 +572,7 @@ def _resume_metadata(project: Path, journal: dict[str, object], path: Path) -> N
             raise PipelineStateError("promotion journal has invalid metadata")
         if current == desired:
             continue
-        if pipeline_state._sha256(current) != expected_original:
+        if state_checkpoint._sha256(current) != expected_original:
             raise PipelineStateError(f"promotion metadata drifted: {target}")
         pipeline_state._atomic_write(target, desired)
         journal["stage"] = f"updated:{target.name}"
@@ -560,9 +590,9 @@ def _resume_next_removal(
         if residual.exists() or residual.is_symlink():
             raise PipelineStateError("promotion has both next track and residual staging")
         next_text = pipeline_state._read_real_file(next_root / "STATE.md", "next/STATE.md")
-        if pipeline_state._sha256(next_text) != journal.get("next_state_sha256"):
+        if state_checkpoint._sha256(next_text) != journal.get("next_state_sha256"):
             raise PipelineStateError("lookahead STATE drifted during promotion")
-        if pipeline_state._tree_digest(next_root) != journal.get("residual_sha256"):
+        if state_checkpoint._tree_digest(next_root) != journal.get("residual_sha256"):
             raise PipelineStateError("lookahead residual drifted during promotion")
         next_root.rename(residual)
         journal["stage"] = "next-staged"
@@ -574,7 +604,7 @@ def _resume_next_removal(
         raise PipelineStateError("promotion lost next track and residual staging")
     if residual.is_symlink() or not residual.is_dir():
         raise PipelineStateError(f"promotion residual must be a real directory: {residual}")
-    if pipeline_state._tree_digest(residual) != journal.get("residual_sha256"):
+    if state_checkpoint._tree_digest(residual) != journal.get("residual_sha256"):
         raise PipelineStateError("staged lookahead residual drifted during promotion")
 
 
@@ -714,30 +744,3 @@ def promote_next(
         "commit": commit,
         "drift": journal["drift"],
     }
-
-
-# pipeline_state imports this module, so the parent is resolved after the
-# definitions above. Parent functions are looked up on the module at call time
-# so patches applied to pipeline_state stay visible here.
-if __package__:  # imported as scripts.state_promote
-    from . import pipeline_state
-    from .pipeline_state import (
-        NULL,
-        PROMOTION_RESIDUAL,
-        PROMOTION_SCHEMA,
-        PROMOTION_TRACKS,
-        SLUG_RE,
-        PipelineState,
-        PipelineStateError,
-    )
-else:  # standalone script or sibling import
-    import pipeline_state
-    from pipeline_state import (
-        NULL,
-        PROMOTION_RESIDUAL,
-        PROMOTION_SCHEMA,
-        PROMOTION_TRACKS,
-        SLUG_RE,
-        PipelineState,
-        PipelineStateError,
-    )

package/skills/gsd-path/scripts/status_runtime.py

@@ -0,0 +1,208 @@
+#!/usr/bin/env python3
+"""Launch the project status runtime across an atomic refresh handoff."""
+
+import argparse
+import hashlib
+import errno
+import json
+import os
+import subprocess
+import sys
+import time
+from pathlib import Path
+from typing import Sequence
+
+PROJECT_STATUS_MARKER = "gsd-path project status launcher"
+INSTALL_LOCK_OWNER = "owner.json"
+INSTALL_LOCK_SCHEMA = "gsd-path/install-lock/v2"
+
+
+def process_identity(pid: int):
+    if os.name == "nt":
+        command = [
+            "powershell.exe",
+            "-NoProfile",
+            "-NonInteractive",
+            "-Command",
+            f"(Get-Process -Id {pid} -ErrorAction Stop).StartTime.ToUniversalTime().Ticks",
+        ]
+    else:
+        command = ["ps", "-o", "lstart=", "-p", str(pid)]
+    try:
+        result = subprocess.run(command, capture_output=True, text=True, check=False)
+    except OSError:
+        return None
+    value = result.stdout.strip()
+    return f"{os.name}:{value}" if result.returncode == 0 and value else None
+
+
+def runtime_identity(runtime: Path):
+    try:
+        status = runtime.stat()
+    except FileNotFoundError:
+        return None
+    return (status.st_dev, status.st_ino, status.st_mtime_ns, status.st_size)
+
+
+def process_alive(pid: int) -> bool:
+    try:
+        os.kill(pid, 0)
+    except OSError as error:
+        return error.errno == errno.EPERM
+    return True
+
+
+def install_lock_active(lock: Path) -> bool:
+    if lock.is_symlink() or not lock.is_dir():
+        return False
+    try:
+        owner = json.loads((lock / INSTALL_LOCK_OWNER).read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError):
+        return False
+    pid = owner.get("pid")
+    valid_pid = isinstance(pid, int) and not isinstance(pid, bool) and pid > 0
+    identity = owner.get("identity")
+    if (
+        owner.get("schema") != INSTALL_LOCK_SCHEMA
+        or not valid_pid
+        or not isinstance(identity, str)
+    ):
+        return False
+    current_identity = process_identity(pid)
+    if current_identity is None:
+        return process_alive(pid)
+    return current_identity == identity
+
+
+RUNTIME_SCHEMA = "gsd-path/runtime/v1"
+
+
+def runtime_home() -> Path:
+    return Path.home() / ".gsd-path" / "runtimes"
+
+
+def declaration(repo: Path) -> dict:
+    path = repo / ".gsd-path" / "runtime.json"
+    if path.is_symlink() or path.parent.is_symlink():
+        raise ValueError(f"unsafe runtime declaration: {path}")
+    data = json.loads(path.read_text(encoding="utf-8"))
+    if (not isinstance(data, dict) or data.get("schema") != RUNTIME_SCHEMA
+            or not isinstance(data.get("version"), str)
+            or not isinstance(data.get("digest"), str)
+            or len(data["digest"]) != 64
+            or any(c not in "0123456789abcdef" for c in data["digest"])):
+        raise ValueError(f"invalid runtime declaration: {path}")
+    return data
+
+
+def manifest_digest(manifest: dict) -> str:
+    return hashlib.sha256(json.dumps(manifest, sort_keys=True, separators=(",", ":")).encode()).hexdigest()
+
+
+def validate_runtime(data: dict) -> Path:
+    root = runtime_home() / data["digest"]
+    hint = (f"Runtime {data['version']} ({data['digest']}) is unavailable or invalid at {root}. "
+            "Run gsd-path --runtime-restore --project <project-root> "
+            "--source-root <matching-package-root> to restore this exact runtime.")
+    try:
+        if any(p.is_symlink() for p in (root, root.parent, root.parent.parent)):
+            raise ValueError("symlinked runtime storage")
+        manifest_path = root / "manifest.json"
+        if manifest_path.is_symlink():
+            raise ValueError("symlinked manifest")
+        manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+        if (not isinstance(manifest, dict) or manifest_digest(manifest) != data["digest"]
+                or manifest.get("version") != data["version"]):
+            raise ValueError("manifest identity mismatch")
+        files = manifest.get("files")
+        if not isinstance(files, dict) or "pipeline_state.py" not in files:
+            raise ValueError("invalid runtime file inventory")
+        for name, expected in files.items():
+            if Path(name).name != name or not name.endswith(".py"):
+                raise ValueError("invalid runtime file name")
+            path = root / name
+            if path.is_symlink() or hashlib.sha256(path.read_bytes()).hexdigest() != expected:
+                raise ValueError(f"runtime file changed: {name}")
+        if set(p.name for p in root.iterdir()) != set(files) | {"manifest.json"}:
+            raise ValueError("unexpected runtime files")
+    except (OSError, ValueError, TypeError) as error:
+        raise ValueError(hint + f" ({error})") from error
+    return root
+
+
+def resolve_runtime(repo: Path) -> Path:
+    return validate_runtime(declaration(repo))
+
+
+def run_guard(repo: Path, name: str) -> None:
+    # Keep the guard's project identity while executing verified external bytes.
+    root = resolve_runtime(repo)
+    sys.dont_write_bytecode = True
+    sys.path.insert(0, str(root))
+    code = compile((root / name).read_bytes(), str(root / name), "exec")
+    exec(code, {"__name__": "__main__", "__file__": str(repo / ".gsd-path" / name)})
+
+
+def launch(repo: Path) -> int:
+    parent = repo / ".gsd-path"
+    if os.path.lexists(parent / "runtime.json"):
+        try:
+            runtime = resolve_runtime(repo) / "pipeline_state.py"
+        except (OSError, ValueError) as error:
+            print(str(error), file=sys.stderr)
+            return 2
+        return subprocess.call([sys.executable, "-B", str(runtime), "status", "--repo", str(repo)],
+                               env={**os.environ, "GIT_OPTIONAL_LOCKS": "0"})
+    runtime = parent / "runtime" / "pipeline_state.py"
+    lock = repo / ".gsd-path-install-lock"
+    command = [sys.executable, "-B", str(runtime), "status", "--repo", str(repo)]
+    environment = os.environ.copy()
+    environment["GIT_OPTIONAL_LOCKS"] = "0"
+    while True:
+        if install_lock_active(lock):
+            time.sleep(0.05)
+            continue
+        before = runtime_identity(runtime)
+        if before is None:
+            if install_lock_active(lock):
+                continue
+            if runtime_identity(runtime) is not None:
+                continue
+            if install_lock_active(lock):
+                continue
+            print(f"GSD Path status runtime is unavailable: {runtime}", file=sys.stderr)
+            return 2
+        try:
+            result = subprocess.run(
+                command, capture_output=True, check=False, env=environment
+            )
+        except OSError as error:
+            print(f"GSD Path status runtime failed: {error}", file=sys.stderr)
+            return 2
+        if install_lock_active(lock) or runtime_identity(runtime) != before:
+            continue
+        sys.stdout.write(result.stdout.decode())
+        sys.stderr.write(result.stderr.decode())
+        return result.returncode
+
+
+def main(argv: Sequence[str] = sys.argv[1:]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--repo", required=True, type=Path)
+    parser.add_argument("--runtime-path", action="store_true")
+    args = parser.parse_args(argv)
+    if not args.repo.is_absolute():
+        print("GSD Path status repository must be absolute", file=sys.stderr)
+        return 2
+    if args.runtime_path:
+        try:
+            print(resolve_runtime(args.repo.resolve()))
+            return 0
+        except (OSError, ValueError) as error:
+            print(str(error), file=sys.stderr)
+            return 2
+    return launch(args.repo.resolve())
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/gsd-path/scripts/task_context.py

@@ -0,0 +1,73 @@
+#!/usr/bin/env python3
+"""Render a read-only coder intent view from the approved task and intent."""
+
+import argparse
+import hashlib
+import re
+import sys
+from pathlib import Path
+
+try:
+    from scripts import check_handoffs as contracts
+except ImportError:
+    import check_handoffs as contracts
+
+
+def render(repo: Path, task: Path) -> str:
+    intent_path = repo.resolve() / '.project/intent/INTENT.md'
+    task = task.resolve()
+    intent = intent_path.read_bytes().decode('utf-8')
+    task_text = task.read_bytes().decode('utf-8')
+    owned = contracts._owned_criteria(task_text, task.stem)
+    criteria = contracts._success_criteria(intent)
+    unknown = set(owned) - set(criteria)
+    if unknown:
+        raise contracts.HandoffError('unknown owned criteria: ' + ', '.join(sorted(unknown)))
+    projected, mode = intent, 'full-intent'
+    sections = list(re.finditer(r'(?ms)^## Success criteria[ \t]*\n(?P<body>.*?)(?=^## |\Z)', intent))
+    if len(sections) == 1:
+        section = sections[0]
+        body = section['body']
+        items = list(re.finditer(r'(?m)^(\d+)\. .+\n?', body))
+        # Project only simple numbered prose. Preserve unfamiliar Markdown in full.
+        simple = (items and not body[:items[0].start()].strip()
+                  and '```' not in body and '~~~' not in body and '<!--' not in body
+                  and [f'SC{item[1]}' for item in items] == list(criteria))
+        chunks = [body[item.start():items[n + 1].start() if n + 1 < len(items) else len(body)]
+                  for n, item in enumerate(items)]
+        simple = simple and all(not line.strip() or line[:1].isspace()
+                                for chunk in chunks for line in chunk.splitlines()[1:])
+        if simple:
+            before, after = intent[:section.start('body')], intent[section.end('body'):]
+            # Corrections and task interfaces can explicitly refer to another SC.
+            required = set(owned) | set(re.findall(r'\bSC\d+\b', before + after + task_text))
+            selected = ''.join(chunk for item, chunk in zip(items, chunks) if f'SC{item[1]}' in required)
+            projected = before + '\n' + (selected or '- No criteria assigned.\n\n') + after
+            mode = 'owned-criteria'
+    return ('## Generated intent context\n\n'
+            f'Source: {intent_path}\n'
+            f'Intent SHA256: {hashlib.sha256(intent.encode()).hexdigest()}\n'
+            f'Task: {task}\n'
+            f'Task SHA256: {hashlib.sha256(task_text.encode()).hexdigest()}\n'
+            f'Mode: {mode}\n\n'
+            'Use this view for intent. All non-criterion text is verbatim; selected criteria retain '
+            'their original numbers. The source remains authoritative. Read it if a dependency '
+            'or ambiguity requires omitted criteria.\n\n' + projected)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--repo', type=Path, required=True)
+    parser.add_argument('--task', type=Path, required=True)
+    args = parser.parse_args()
+    try:
+        output = render(args.repo, args.task)
+    except (OSError, contracts.HandoffError) as error:
+        print(str(error), file=sys.stderr)
+        return 1
+    print(output, end='')
+    return 0
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())

package/skills/gsd-path/scripts/token_budget.py

@@ -69,6 +69,24 @@ def output_usage(path: Path) -> int:
     return sum(usages)
 
 
+def cumulative_counter(path: Path):
+    """One completed CLI invocation, with the thread identity needed for resume."""
+    identities, counters = set(), []
+    for line in path.read_text(encoding="utf-8").splitlines():
+        event = json.loads(line)
+        if "raw" in event:
+            event = json.loads(event["raw"])
+        if event.get("type") == "thread.started":
+            identities.add(event["thread_id"])
+        if event.get("type") == "turn.completed":
+            counters.append(event["usage"]["output_tokens"])
+    if len(identities) != 1 or len(counters) != 1:
+        raise ValueError("cumulative usage requires one identified, completed CLI invocation")
+    if type(counters[0]) is not int or counters[0] < 0:
+        raise ValueError("invalid cumulative output counter")
+    return identities.pop(), counters[0]
+
+
 def operate(args):
     ledger = args.ledger.absolute()
     if ledger.is_symlink():
@@ -92,9 +110,28 @@ def operate(args):
         if args.action == "record":
             source = str(args.events.resolve())
             observation = {"task": args.task, "output_tokens": output_usage(args.events)}
+            prior_events = getattr(args, "previous_events", None)
+            if prior_events is not None:
+                prior_source = str(prior_events.resolve())
+                prior = data["observations"].get(prior_source)
+                identity, total = cumulative_counter(args.events)
+                prior_identity, prior_total = cumulative_counter(prior_events)
+                if source == prior_source or identity != prior_identity or total < prior_total:
+                    raise ValueError("cumulative resume has a different thread or a reset counter")
+                if prior is None or prior.get("reported_output_tokens", prior["output_tokens"]) != prior_total:
+                    raise ValueError("previous cumulative invocation must be recorded unchanged first")
+                if any(key != source and row.get("previous_events") == prior_source
+                       for key, row in data["observations"].items()):
+                    raise ValueError("previous cumulative invocation already has a recorded successor")
+                observation.update(output_tokens=total - prior_total, reported_output_tokens=total,
+                                   previous_events=prior_source, session_id=identity)
             previous = data["observations"].get(source)
+            if previous and previous != observation and any(
+                    row.get("previous_events") == source for row in data["observations"].values()):
+                raise ValueError("a cumulative predecessor cannot change after its successor is recorded")
             if previous and (previous["task"] != args.task or
-                             previous["output_tokens"] > observation["output_tokens"]):
+                             previous["output_tokens"] > observation["output_tokens"] or
+                             previous.get("previous_events") != observation.get("previous_events")):
                 raise ValueError("observation cannot change task or reduce recorded usage")
             data["observations"][source] = observation
             atomic_write(ledger, json.dumps(data, indent=2) + "\n")
@@ -131,6 +168,8 @@ def main(argv=None):
             command.add_argument("--task", required=True)
         if name == "record":
             command.add_argument("--events", type=Path, required=True)
+            command.add_argument("--previous-events", type=Path,
+                                 help="previous recorded invocation when this CLI reports cumulative resume counters")
         if name == "admit":
             command.add_argument("--require-hard-cap", action="store_true")
     try: