@opengsd/gsd-path 1.0.0 → 1.1.0

package/skills/gsd-path-docs-audit/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-forensics/scripts/pipeline_diagnose.py

@@ -21,6 +21,7 @@ def _load_diagnose_modules():
         import archive_milestone
         import detect_project
         import discussion_records
+        import integration
         import isolation
         import pipeline_git
         import pipeline_state
@@ -28,6 +29,7 @@ def _load_diagnose_modules():
             archive_milestone,
             detect_project,
             discussion_records,
+            integration,
             isolation,
             pipeline_git,
             pipeline_state,
@@ -37,6 +39,7 @@ def _load_diagnose_modules():
             "archive_milestone",
             "detect_project",
             "discussion_records",
+            "integration",
             "isolation",
             "pipeline_git",
             "pipeline_state",
@@ -47,6 +50,7 @@ def _load_diagnose_modules():
             archive_milestone,
             detect_project,
             discussion_records,
+            integration,
             isolation,
             pipeline_git,
             pipeline_state,
@@ -55,6 +59,7 @@ def _load_diagnose_modules():
             archive_milestone,
             detect_project,
             discussion_records,
+            integration,
             isolation,
             pipeline_git,
             pipeline_state,
@@ -65,6 +70,7 @@ def _load_diagnose_modules():
             "scripts.archive_milestone",
             "scripts.detect_project",
             "scripts.discussion_records",
+            "scripts.integration",
             "scripts.isolation",
             "scripts.pipeline_git",
             "scripts.pipeline_state",
@@ -75,6 +81,7 @@ def _load_diagnose_modules():
         import archive_milestone
         import detect_project
         import discussion_records
+        import integration
         import isolation
         import pipeline_git
         import pipeline_state
@@ -82,6 +89,7 @@ def _load_diagnose_modules():
             archive_milestone,
             detect_project,
             discussion_records,
+            integration,
             isolation,
             pipeline_git,
             pipeline_state,
@@ -92,6 +100,7 @@ def _load_diagnose_modules():
     archive_milestone,
     detect_project,
     discussion_records,
+    integration,
     isolation,
     pipeline_git,
     pipeline_state,
@@ -477,8 +486,8 @@ def diagnose(repo: Path) -> dict[str, object]:
             else:
                 if state.get("phase") == "shipped" and state.get("milestone"):
                     try:
-                        archive_milestone.validate_integrated(
-                            resolved, str(state["milestone"])
+                        integration.validate_integrated(
+                            resolved, str(state["milestone"]), refresh=False
                         )
                     except archive_milestone.ArchiveError as error:
                         findings.append(
@@ -585,7 +594,7 @@ def diagnose(repo: Path) -> dict[str, object]:
                 expected_worktree = None
                 if archive:
                     expected_branch, expected_worktree = (
-                        archive_milestone.integration_names(
+                        integration.integration_names(
                             resolved,
                             Path(archive).name,
                         )

package/skills/gsd-path-forensics/scripts/pipeline_undo.py

@@ -27,18 +27,20 @@ def _load_pipeline_modules():
         import isolation
         import pipeline_git
         import pipeline_state
-        return archive_milestone, isolation, pipeline_git, pipeline_state
+        import state_checkpoint
+        return archive_milestone, isolation, pipeline_git, pipeline_state, state_checkpoint
     except ModuleNotFoundError as error:
         if error.name not in {
             "archive_milestone",
             "isolation",
             "pipeline_git",
             "pipeline_state",
+            "state_checkpoint",
         }:
             raise
     try:
-        from scripts import archive_milestone, isolation, pipeline_git, pipeline_state
-        return archive_milestone, isolation, pipeline_git, pipeline_state
+        from scripts import archive_milestone, isolation, pipeline_git, pipeline_state, state_checkpoint
+        return archive_milestone, isolation, pipeline_git, pipeline_state, state_checkpoint
     except ModuleNotFoundError as error:
         if error.name not in {
             "scripts",
@@ -46,6 +48,7 @@ def _load_pipeline_modules():
             "scripts.isolation",
             "scripts.pipeline_git",
             "scripts.pipeline_state",
+            "scripts.state_checkpoint",
         }:
             raise
         shared = Path(__file__).resolve().parents[2] / "gsd-path" / "scripts"
@@ -54,16 +57,17 @@ def _load_pipeline_modules():
         import isolation
         import pipeline_git
         import pipeline_state
-        return archive_milestone, isolation, pipeline_git, pipeline_state
+        import state_checkpoint
+        return archive_milestone, isolation, pipeline_git, pipeline_state, state_checkpoint
 
 
-archive_milestone, isolation, pipeline_git, pipeline_state = _load_pipeline_modules()
+archive_milestone, isolation, pipeline_git, pipeline_state, state_checkpoint = _load_pipeline_modules()
 ArchiveError = archive_milestone.ArchiveError
 IsolationError = isolation.IsolationError
 PLAN_APPROVAL_SUBJECT = pipeline_state.PLAN_APPROVAL_SUBJECT
 PipelineStateError = pipeline_state.PipelineStateError
-_activate_roadmap_milestone = pipeline_state._activate_roadmap_milestone
-_approval_details = pipeline_state._approval_details
+_activate_roadmap_milestone = state_checkpoint._activate_roadmap_milestone
+_approval_details = state_checkpoint._approval_details
 _commit_subject_body = pipeline_state._commit_subject_body
 _optional_rev = pipeline_state._optional_rev
 _render_transition = pipeline_state._render_transition

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

@@ -21,10 +21,12 @@ phase blocks.
 
 If STATE.md is missing, run the bundled
 `python3 <absolute-bundled-script> initialize --repo <absolute-root>
---template <absolute-state-template>` helper (`scripts/detect_project.py`) and
+--template <absolute-state-template> --require-git` helper (`scripts/detect_project.py`) and
 follow its returned JSON `verdict` / `route`. This is the only no-state
 boundary; do not run `classify` first or classify from a directory listing or
-conversation. If the command exits nonzero, returns `error`, or returns
+conversation. Handle `route: setup-repository` before the write gate: preserve
+the folder unchanged and return to `$gsd-path` for repository setup; no state
+was written. If the command exits nonzero, returns `error`, or returns
 `wrote_state: false`, report the error and block without routing or claiming
 STATE.md was written.
 - `owned` — continue under the existing-state rules below.
@@ -47,6 +49,31 @@ same milestone; a later milestone's `inspect/active` is a new scan.
 
 ## Process
 
+For an initial `inspect/active` inspection on the `.project` track, with neither output
+artifact present and a clean Git product at the recorded HEAD, run the bundled
+`python3 <absolute workflow_run.py> prepare-inspect --repo <absolute root>
+--expected-head <recorded HEAD>` first. It performs the inventory freeze and
+both sidecar preparations from steps 1–2 and writes complete assignment briefs.
+Its state validation and pending-answer check satisfy those entry checks;
+reuse their results at this boundary.
+Use its returned `inspection.inventory_file` for the gate. Before dispatch, read
+and apply the [runtime dispatch contract](references/dispatch.md), including its
+host-specific context isolation. Dispatch each returned logical `task_name` in a fresh context with its `brief_file` path and the current
+user constraints, including configured budgets. The child reads that file;
+the parent does not read or rewrite the roles, templates, or generated briefs.
+When both children return, review the mapper's Map and Findings against its
+template as in step 3. After that review passes, run the bundled
+`python3 <absolute workflow_run.py> finish-inspect --repo <absolute root>
+--expected-head <recorded HEAD> --inspection <returned receipt_file>
+--mapper-reviewed`. This runs the docs gate, checks the audit baseline,
+collects and retires both sidecars, checks pending discussion, and records
+`inspect/done` through the canonical transition. Do not repeat those operations.
+Present step 4's ground truth and use step 5's caller handoff. A failure uses
+step 3's failure contract and the returned step evidence; do not blindly rerun
+the completion command or repeat already proven steps.
+Prior evidence, lookahead, or a dirty/non-Git product uses steps 1–2 below.
+Preparation never changes phase state; neither command dispatches agents.
+
 1. Before creating or changing `.project/` Markdown, freeze the helper's exact
    stdout from `python3 <absolute check_docs_audit.py> --repo <absolute root>
    --emit-inventory` in a temporary file. Do not rediscover or edit that
@@ -132,12 +159,7 @@ same milestone; a later milestone's `inspect/active` is a new scan.
    <current branch or null> --expect-archive <current archive or null>
    --set-phase inspect --set-status done`. This helper is the only ordinary
    STATE mutation; require its returned state to be `inspect/done`.
-   Identify `$gsd-path-define` as next. When this phase was routed by an
-   active `$gsd-path`, return control to that router so its bundled define
-   contract runs in brownfield mode (and milestone mode when ROADMAP.md
-   exists). When invoked directly, stop and tell the
-   user to explicitly invoke `$gsd-path`, which routes to define; do not invoke
-   an explicit-only sibling skill yourself.
+   Use the executable phase handoff in AGENTS.md.
 
 ## Lookahead mode
 

package/skills/gsd-path-inspect/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-inspect/references/docs-auditor.md

@@ -24,6 +24,20 @@ actually does. Read-only: change nothing outside your single output file.
    `## Descriptive docs` list — never its own section, never skipped.
 2. **Extract claims** — statements reality can contradict: commands,
    features, structure, status/checkboxes, config, integrations.
+   Scope each claim to this repository's product. An exclusion is a scope
+   boundary, not an evidence gap: do not create `unverifiable` findings or
+   remediation rows for the implementation of an excluded dependency. In an
+   application that installs GSD Path, descriptions of GSD Path's source
+   distribution and pipeline internals are such dependency claims. In GSD
+   Path's own source repository, they are product claims and must be audited.
+   Keep application commands, configuration, and integration promises in
+   scope even when they use a dependency. In a mixed document, audit those
+   product claims; if none remain, list its exact inventory path alone in
+   Descriptive docs. Put a short scope reason in a separate paragraph, never
+   on a path bullet. Remediation Doc cells also use exact inventory paths;
+   copy each non-verified Claim cell verbatim into its remediation row, and
+   put line numbers in Evidence. This never exempts instructions from being
+   followed or conflicting instructions from being surfaced.
 3. **Verify each claim** by the cheapest sufficient method: run the
    command, read the named code, run the relevant test, check git history.
    Record the evidence (file:line, or command + result) with the verdict: