@opengsd/gsd-path 1.0.0 → 1.1.0

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

@@ -11,6 +11,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 +268,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 +290,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 +298,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 +463,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 +489,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 +546,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 +567,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 +585,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 +599,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 +739,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-roadmap/SKILL.md

@@ -143,69 +143,33 @@ precondition fails.
    retain the entering state for a milestone-boundary re-slice; otherwise keep
    `phase: roadmap`, `status: active`. Retain the baseline, revise, and re-gate
    against that same baseline.
-7. On approval in an established repository, record the exact full current
-   HEAD before changing ROADMAP.md or STATE.md. For a milestone-boundary
-   re-slice, keep its matching roadmap entry `active`, use `pipeline_state.py
-   transition` to record `program roadmap re-slice approved` while expecting
-   and retaining the complete entering `inspect/active` or `define/active`
-   state, then checkpoint the pending `.project/` artifacts with:
-
-   ```text
-   python3 <absolute isolation.py> checkpoint \
-     --repo <absolute root> --expected-head <recorded full HEAD> \
-     --subject "roadmap: program roadmap approved" \
-     --body "Why: approved roadmap checkpoint" \
-     --allow-path .project
-   ```
-
-   On a post-abandon re-slice, mark only the helper-selected pending entry
-   `active`, use `pipeline_state.py transition` with the complete current
-   `roadmap/active` state as expected to set `phase: inspect`, `status: active`,
-   `milestone` to the selected slug, preserve the bound branch, and set
-   `archive: null`, with an event naming the abandoned predecessor. Then use
-   the same `isolation.py checkpoint` command above. For a first roadmap
-   approval, run:
+7. On approval, record the full current HEAD and use the bundled approval
+   module. For a first roadmap approval use `--kind roadmap`; for either
+   re-slice use `--kind roadmap-reslice`. In a milestone-boundary re-slice,
+   `--milestone` is the unchanged active milestone; after abandon, it is the
+   helper-selected pending milestone reviewed by the user.
 
    ```text
    python3 <absolute pipeline_state.py> approve \
-     --repo <absolute root> --kind roadmap \
-     --milestone <selected first pending slug> \
-     --expected-head <recorded full HEAD>
+     --repo <absolute root> --kind roadmap-reslice \
+     --milestone <reviewed milestone slug> --expected-head <recorded full HEAD>
    ```
 
-   The helper journals before mutation, proves the selected entry is pending
-   and no entry is already active, marks it active, changes STATE from
-   `roadmap/active` to `roadmap/done` with that milestone and event `program
-   roadmap approved`, and checkpoints all pending `.project/` artifacts with
-   the canonical roadmap subject and body, subject to the
-   top-level allowlist in
-   [isolation.PROJECT_ENTRIES](scripts/isolation.py). Require its typed result to report
-   `schema: gsd-path/state-checkpoint/v1`, `status: approved`, `kind: roadmap`,
-   `project_dir: .project`, `state.status: done`, the selected milestone, and
-   the returned current commit. Rerun the same command after interruption; the
-   matching journal owns recovery.
-
-   For every re-slice, remove `.project/ROADMAP.before-reslice.md` only after
-   the state transition succeeds and before the checkpoint. Retain it through
-   every requested revision and failed approval attempt.
-
-   Defer either checkpoint only when the directory is not yet a Git repository
-   or `.project/REPOSITORY.md` records `Kind: new-github`. For a normal
-   approval, run the same `approve` command with `--defer-checkpoint` instead
-   of `--expected-head`; it marks the selected entry active and records
-   `roadmap/done` with event `program roadmap approved`. `pipeline_state.py
-   transition` never approves a roadmap. For
-   a milestone-boundary re-slice, use the retaining transition above; for a
-   post-abandon re-slice, use its transition above. The build transition
-   commit owns the pending artifacts. Confirm approval and link ROADMAP.md again. For
-   a milestone-boundary re-slice, state that the preserved inspect or define
-   phase resumes; for a post-abandon re-slice, state that inspect is next;
-   otherwise state that define (milestone mode) is next. Do not
-   add another approval gate. When routed by an active `$gsd-path`, return
-   control to that router so it routes the resulting state; never name define
-   as next when inspect was preserved or selected. When invoked directly, stop
-   and tell the user to explicitly invoke `$gsd-path`, which routes the same
-   result; do not invoke an explicit-only sibling skill yourself.
+   The helper owns roadmap selection, expected state, baseline cleanup and
+   the approval checkpoint. It journals before mutation, retains the baseline
+   bytes for recovery, and refuses changes to settled or active entries.
+   A milestone-boundary re-slice retains Inspect or Define; a post-abandon
+   re-slice enters Inspect. Require its typed result to report `status:
+   approved`, the requested kind, milestone and returned commit. After an
+   interruption, follow the router's `resume-checkpoint` action; do not edit
+   state, delete the baseline or checkpoint separately.
+
+   Before Git exists, or during a `Kind: new-github` transaction, use the same
+   approval command with `--defer-checkpoint` instead of `--expected-head`.
+   That existing deferred path writes the metadata without a Git journal or
+   commit; the next build checkpoint owns it. Retain the baseline through
+   revisions and rejected approvals. Confirm approval, link ROADMAP.md again,
+   and use the executable phase handoff in AGENTS.md without another gate.
 
 ## Rules
 

package/skills/gsd-path-roadmap/references/dispatch.md

@@ -122,6 +122,12 @@ directory for the full logical session; resumptions reuse it. Record completed
 parent CLI run events and each native child's session events with stable logical
 task names before the next dispatch. The helper reads host counters and refuses
 incomplete or ambiguous usage; never estimate tokens or reset the ledger.
+When the verified CLI adapter reports cumulative counters across `resume`, record
+each later invocation with `--previous-events <previous recorded CLI events>`.
+The helper checks thread identity and records only the new output, preserving the
+raw total and predecessor. Keep that chain in order; never sum cumulative totals.
+Use ordinary `record` for per-invocation counters. An unknown counter convention
+is unproven usage, not permission to guess.
 Run `admit` for the next task and stop dispatch on a blocked result. Preserve
 its output in the dispatch evidence. This gates observed usage only: concurrent
 or in-flight work can overrun before the host reports usage. Codex CLI has no

package/skills/gsd-path-roadmap/scripts/archive_milestone.py

@@ -239,15 +239,10 @@ class ArchiveError(RuntimeError):
 
 
 PIPELINE_MARKER = _common.PIPELINE_MARKER
-PR_CREDIT_LINE = (
-    "PR prepared with [GSD Path](https://github.com/open-gsd/gsd-path)."
-)
-GITHUB_HOST = "github.com"
 
 
-# discussion_validate and integration call back into this module through a
-# module reference and import the constants and ArchiveError above, so this
-# import must stay below those definitions.
+# discussion_validate calls back into this module and imports its constants
+# and ArchiveError, so this import must stay below those definitions.
 if __package__:  # imported as scripts.archive_milestone
     from .discussion_validate import (
         record_sections,
@@ -280,42 +275,6 @@ if __package__:  # imported as scripts.archive_milestone
         render_manifest,
         validate_manifest,
     )
-    from .integration import (
-        resolve_remote_default,
-        live_remote_ref,
-        publish_bound_branch,
-        refresh_origin,
-        optional_ref,
-        integration_names,
-        registered_worktree,
-        remove_registered_worktree,
-        delete_integration_branch,
-        require_generated_integration_commit,
-        discard_unpublished_stale_integration,
-        create_integration_merge,
-        require_annotated_tag,
-        ensure_integration_tag,
-        github_repository,
-        require_github_authentication,
-        github_api_json,
-        require_pull_request_shape,
-        require_pull_request_pages,
-        pull_request_head_matches_repository,
-        require_pull_request_identity,
-        find_pull_request,
-        pull_request_body,
-        update_pull_request_body,
-        create_pull_request,
-        pull_request_tag_message,
-        pull_request_tag_metadata,
-        require_pull_request_merge,
-        require_pull_request_merge_provenance,
-        integrate_pull_request,
-        integrate,
-        find_integrate_commit,
-        validate_integrated,
-        require_published_integration,
-    )
 else:  # standalone script or sibling import
     if __name__ == "__main__":
         sys.modules.setdefault("archive_milestone", sys.modules[__name__])
@@ -351,42 +310,6 @@ else:  # standalone script or sibling import
             render_manifest,
             validate_manifest,
         )
-        from integration import (
-            resolve_remote_default,
-            live_remote_ref,
-            publish_bound_branch,
-            refresh_origin,
-            optional_ref,
-            integration_names,
-            registered_worktree,
-            remove_registered_worktree,
-            delete_integration_branch,
-            require_generated_integration_commit,
-            discard_unpublished_stale_integration,
-            create_integration_merge,
-            require_annotated_tag,
-            ensure_integration_tag,
-            github_repository,
-            require_github_authentication,
-            github_api_json,
-            require_pull_request_shape,
-            require_pull_request_pages,
-            pull_request_head_matches_repository,
-            require_pull_request_identity,
-            find_pull_request,
-            pull_request_body,
-            update_pull_request_body,
-            create_pull_request,
-            pull_request_tag_message,
-            pull_request_tag_metadata,
-            require_pull_request_merge,
-            require_pull_request_merge_provenance,
-            integrate_pull_request,
-            integrate,
-            find_integrate_commit,
-            validate_integrated,
-            require_published_integration,
-        )
     except ImportError:  # pragma: no cover - package import used by tests
         from scripts.discussion_validate import (
             record_sections,
@@ -419,42 +342,6 @@ else:  # standalone script or sibling import
             render_manifest,
             validate_manifest,
         )
-        from scripts.integration import (
-            resolve_remote_default,
-            live_remote_ref,
-            publish_bound_branch,
-            refresh_origin,
-            optional_ref,
-            integration_names,
-            registered_worktree,
-            remove_registered_worktree,
-            delete_integration_branch,
-            require_generated_integration_commit,
-            discard_unpublished_stale_integration,
-            create_integration_merge,
-            require_annotated_tag,
-            ensure_integration_tag,
-            github_repository,
-            require_github_authentication,
-            github_api_json,
-            require_pull_request_shape,
-            require_pull_request_pages,
-            pull_request_head_matches_repository,
-            require_pull_request_identity,
-            find_pull_request,
-            pull_request_body,
-            update_pull_request_body,
-            create_pull_request,
-            pull_request_tag_message,
-            pull_request_tag_metadata,
-            require_pull_request_merge,
-            require_pull_request_merge_provenance,
-            integrate_pull_request,
-            integrate,
-            find_integrate_commit,
-            validate_integrated,
-            require_published_integration,
-        )
 
 
 @contextmanager
@@ -2238,6 +2125,11 @@ def parser() -> argparse.ArgumentParser:
 def main(argv: Optional[Sequence[str]] = None) -> int:
     arguments = parser().parse_args(argv)
     try:
+        if arguments.command in {"validate-integrated", "refresh-origin", "integrate"}:
+            if __package__:
+                from . import integration
+            else:
+                import integration
         if arguments.command == "prepare":
             result = prepare(arguments.repo, arguments.slug)
         elif arguments.command == "render-manifest":
@@ -2247,11 +2139,11 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
         elif arguments.command == "abandon":
             result = abandon(arguments.repo, arguments.slug, arguments.reason)
         elif arguments.command == "validate-integrated":
-            result = validate_integrated(arguments.repo, arguments.slug)
+            result = integration.validate_integrated(arguments.repo, arguments.slug)
         elif arguments.command == "refresh-origin":
-            result = refresh_origin(arguments.repo)
+            result = integration.refresh_origin(arguments.repo)
         elif arguments.command == "integrate":
-            result = integrate(arguments.repo, arguments.slug)
+            result = integration.integrate(arguments.repo, arguments.slug)
         else:
             result = validate(arguments.repo)
     except (ArchiveError, OSError) as error: