@opengsd/gsd-path 1.0.0

package/skills/gsd-path-ship/scripts/workflow_run.py

@@ -0,0 +1,117 @@
+#!/usr/bin/env python3
+"""Run canonical workflow helpers with fixed arguments and fail-stop receipts."""
+
+import argparse
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+try:
+    from scripts import _common
+except ImportError:  # bundled copy inside a skill's scripts directory
+    import _common
+
+
+class StepFailed(RuntimeError):
+    pass
+
+
+def run_workflow(repo: Path, action: str, project_dir: str, expected_head: str = None,
+                 task_id: str = None, round_size: int = None) -> dict:
+    steps = []
+    scripts = Path(__file__).resolve().parent
+
+    def step(script, *arguments):
+        command = [sys.executable, "-B", str(scripts / script), *arguments]
+        completed = subprocess.run(command, cwd=repo, capture_output=True, text=True)
+        receipt = {"script": script, "command": command, "exit_code": completed.returncode,
+                   "stdout": completed.stdout, "stderr": completed.stderr}
+        steps.append(receipt)
+        if completed.stderr:
+            sys.stderr.write(completed.stderr)
+        if completed.returncode:
+            raise StepFailed(script)
+        try:
+            receipt["result"] = json.loads(completed.stdout)
+        except json.JSONDecodeError as error:
+            raise StepFailed(f"{script} did not return JSON") from error
+        return receipt["result"]
+
+    common = ["--repo", str(repo), "--project-dir", project_dir]
+    try:
+        if action == "route":
+            step("pipeline_state.py", "route", *common)
+        elif action == "lint-round":
+            head = subprocess.run(["git", "rev-parse", "--verify", "HEAD"],
+                                  cwd=repo, capture_output=True, text=True, check=True).stdout.strip()
+            step("check_task_briefs.py", "--repo", str(repo), "--base", head,
+                 "--tasks-dir", f"{project_dir}/tasks")
+            step("check_handoffs.py", "plan", *common)
+        elif action == "prepare-task":
+            task = step("isolation.py", "isolate-task", "--repo", str(repo),
+                        "--base", expected_head, "--task-id", task_id,
+                        "--round-size", str(round_size))
+            if task["mode"] == "serial":
+                step("isolation.py", "isolate-verify", "--repo", str(repo),
+                     "--base", expected_head, "--name", f"task-{task_id.lower()}-verify")
+        elif action == "build-evidence":
+            proof = step("build_state.py", "verify-landed", *common, "--head", expected_head)
+            # The landing proof has one canonical home; lean final-review reuse allows only this path.
+            evidence = repo / project_dir / "build" / "evidence.json"
+            _common.atomic_write(evidence, json.dumps(proof, indent=2, sort_keys=True) + "\n")
+            steps.append({"script": "workflow_run.py", "evidence": str(evidence)})
+        elif action == "prepare-final":
+            if project_dir != ".project":
+                raise StepFailed("final review requires the active milestone")
+            pending = step("discussion_records.py", "pending", "--repo", str(repo))
+            if pending["pending"]:
+                raise StepFailed("pending discussion requires its owner disposition")
+            step("build_state.py", "verify-landed", *common, "--head", expected_head)
+            step("lean_verification.py", "--repo", str(repo), "--expected-head", expected_head)
+        else:
+            pending = step("discussion_records.py", "pending", "--repo", str(repo))
+            if pending["pending"]:
+                raise StepFailed("pending discussion requires its owner disposition")
+            step("check_handoffs.py", "plan", *common)
+            head = subprocess.run(["git", "rev-parse", "--verify", "HEAD"],
+                                  cwd=repo, capture_output=True, text=True, check=True).stdout.strip()
+            step("check_task_briefs.py", "--repo", str(repo), "--base", head,
+                 "--tasks-dir", f"{project_dir}/tasks")
+            panel = ["validate-plan", "--plan", str(repo / project_dir / "plan/PLAN.md"),
+                     "--intent", str(repo / project_dir / "intent/INTENT.md")]
+            charter = repo / ".project/CHARTER.md"
+            if charter.exists():
+                panel += ["--charter", str(charter)]
+            step("review_panel.py", *panel)
+            if action == "approve-plan":
+                step("pipeline_state.py", "approve", *common, "--kind", "plan",
+                     "--expected-head", expected_head)
+    except (StepFailed, OSError, subprocess.CalledProcessError) as error:
+        return {"status": "blocked", "reason": str(error), "steps": steps,
+                "next": "$gsd-path-forensics"}
+    return {"status": "complete", "steps": steps}
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("action", choices=("route", "gate-plan", "approve-plan", "build-evidence", "lint-round", "prepare-task", "prepare-final"))
+    parser.add_argument("--repo", type=Path, required=True)
+    parser.add_argument("--project-dir", choices=(".project", ".project/next"), default=".project")
+    parser.add_argument("--expected-head")
+    parser.add_argument("--task-id")
+    parser.add_argument("--round-size", type=int)
+    arguments = parser.parse_args(argv)
+    if arguments.action in {"approve-plan", "build-evidence", "prepare-task", "prepare-final"} and not arguments.expected_head:
+        parser.error(f"{arguments.action} requires --expected-head")
+    if arguments.action == "prepare-task" and (not arguments.task_id or arguments.round_size is None):
+        parser.error("prepare-task requires --task-id and --round-size")
+    result = run_workflow(arguments.repo.resolve(), arguments.action,
+                          arguments.project_dir, arguments.expected_head,
+                          arguments.task_id, arguments.round_size)
+    print(json.dumps(result, sort_keys=True))
+    return 0 if result["status"] == "complete" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/gsd-path-ship/templates/archive-manifest.md

@@ -0,0 +1,37 @@
+# Archive — <NNN>-<milestone-slug>
+
+<!-- Written at ship time by $gsd-path-ship final. The archive's table of
+     contents: a future audit must be able to reconstruct the milestone
+     from this file. Append-only once written. The validator requires
+     "Final verdict:" to be exactly the string shown below. -->
+
+Milestone: <name>
+Shipped: <date>
+Final verdict: all criteria met; project verify passed
+Waves: <n>  Tasks: <n> done / <n> total  Review cycles used: <per wave, e.g. 1/2/1>
+Carried forward: <none, or "N DOCS-AUDIT ruling(s)">
+
+## Success criteria at ship
+
+<!-- Evidence is copied verbatim from FINAL.md; escape a literal pipe as
+     \| so the row keeps its three cells. -->
+
+| Criterion | Verdict | Evidence |
+|-----------|---------|----------|
+| <criterion copied from FINAL.md> | met | <FINAL Reference; else Check; else Observed> |
+
+## Contents
+
+<!-- Every file moved into this archive, one per line, relative paths. -->
+- intent/INTENT.md
+- research/...
+- plan/PLAN.md
+- tasks/...
+- review/...
+
+## Notes
+
+<!-- Anything the next milestone should know: escalations that shaped the
+     build, accepted drift, known debt. Write at least one substantive bullet;
+     use "none" if clean. -->
+- <note>

package/skills/gsd-path-ship/templates/final-review.md

@@ -0,0 +1,27 @@
+# Final Review — <project name>
+
+<!-- Authorship and evidence reuse follow the ship phase contract. Each INTENT.md success
+     criterion appears exactly once and carries checked evidence. A criterion
+     listed in PLAN.md's Surface contract also names its Surface, and its
+     Check is the walkthrough performed — never internal test output. Embedded
+     angle brackets are valid in concrete Check and Observed values. -->
+
+Reviewed HEAD: <full SHA>
+Overall verdict: <pass | blocked>
+
+<!-- pass only when every criterion is met; blocked when any criterion is
+     not-met or unverifiable. -->
+
+## Success criteria
+
+### SC1 — <criterion copied verbatim from INTENT.md>
+
+- **Verdict**: <met | not-met | unverifiable>
+- **Surface**: <the surface PLAN.md's Surface contract lists this criterion under; omit the whole field for any other criterion>
+- **Check**: `<command actually run, or "none">`
+- **Observed**: <relevant output or observed behavior>
+- **Reference**: <file:line, artifact path, or "none">
+- **Finding**: <none, or what was found instead>
+- **Fix direction**: <none, or concrete direction for a patch task>
+
+<!-- Repeat once per success criterion, preserving INTENT.md order. -->

package/skills/gsd-path-ship/templates/gap-review.md

@@ -0,0 +1,20 @@
+# Gap Review — <N>: <risk identity>
+
+<!-- Written by one final gap reviewer. This file covers exactly one
+     cross-wave integration risk named in the review brief. -->
+
+Reviewed HEAD: <full SHA>
+Gap verdict: <pass | blocked>
+Risk: <same risk identity as the heading>
+Waves checked: <wave numbers>
+
+## Checked evidence
+
+- **Check**: `<command actually run, or "none">`
+- **Observed**: <relevant output or observed behavior>
+- **Reference**: <file:line, artifact path, or "none">
+
+## Finding
+
+- **Found**: <evidence-backed result>
+- **Fix direction**: <none when pass; concrete direction when blocked>

package/skills/gsd-path-ship/templates/patch-findings.md

@@ -0,0 +1,16 @@
+# Patch Findings
+
+<!-- Written by final review when it blocks and consumed by patch planning. -->
+
+Reviewed HEAD: <full SHA>
+State: ship/blocked
+
+## Findings
+
+<!-- Copy only evidenced, selected findings. Keep IDs contiguous and ordered. -->
+### P001 — <short finding title>
+
+- **Source**: `.project/review/FINAL.md`
+- **Locator**: `<SC number or gap risk row>`
+- **Evidence**: <observed result copied from the source review>
+- **Fix direction**: <concrete direction for the patch task>

package/skills/gsd-path-ship/templates/wave-review.md

@@ -0,0 +1,64 @@
+# Review — wave <N>, cycle <C>
+
+<!-- Written by the reviewer role in wave mode. File: wave-N.cycleC.md —
+     deep reviews use wave-N.cycleC.contract.md and
+     wave-N.cycleC.adversarial.md instead. Keep validated fields on their
+     own lines: Cycle holds only the number
+     (C > 1 means re-review after fixes; see previous cycle file). -->
+
+<!-- For quick single-full-wave final scope, include these two metadata lines
+     with actual values, otherwise omit them:
+Reviewed HEAD: <full review commit SHA>
+Review scope: final
+     In each surface SC block also include Surface, Check, and Observed fields
+     using the final-review format. Record the actual walkthrough evidence once. -->
+
+Wave verdict: <pass | blocked — blocked if any task fails>
+Cycle: <C>
+Depth: <full | deep | verify-only — verify-only is orchestrator-written from
+        its isolated Verify evidence; no independent reviewer ran>
+Lens: <contract | adversarial — deep reviews only; empty or omitted
+       otherwise>
+Tasks reviewed: <count>
+
+## T001 — <title>: <pass | fail>
+
+<!-- Per task criterion: copy the full acceptance/interface criterion verbatim
+     before the em dash; join wrapped lines with spaces. An AC id or summary
+     alone cannot be matched by review_findings.py. -->
+- ✅ <criterion> — <evidence: verify output / file:line checked>
+- ❌ <criterion> — found: <what exists instead, file:line>
+  fix: <concrete direction a coder can execute without re-investigating>
+
+Warnings (non-blocking):
+- <weakened test / unfailable verify / none>
+
+Contract violations (blocking):
+- ❌ <task changed path outside its files list> — <evidence and fix direction>
+
+<!-- Repeat per task. -->
+
+## Intent coverage
+
+<!-- One heading per INTENT.md success criterion owned by a task in this
+     wave, ending `: pass` or `: fail`. `scripts/check_handoffs.py wave
+     --review <this file>` gates the SC id set and verdicts. Omit this
+     section when no task in the wave owns an SC. -->
+
+### SC1 — <criterion>: <pass | fail>
+- ✅ <evidence: verify output / file:line checked>
+- ❌ <criterion> — found: <what exists instead, file:line>
+  fix: <concrete direction a coder can execute without re-investigating>
+
+## Fixed since last cycle
+
+<!-- C > 1 only: previously failed criteria now confirmed fixed (re-checked,
+     not assumed), and any regressions the fixes introduced. -->
+- <criterion> — confirmed fixed / regressed: <evidence>
+
+## Summary for orchestrator
+
+- blocked findings: <failed criteria grouped by disjoint file scope; the
+  orchestrator applies the configured skeptic or fix-task path>
+- repeat offenders: <criteria failing across cycles — possible plan defect>
+- warnings worth a human eye: <...or none>

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

@@ -0,0 +1,45 @@
+---
+name: gsd-path-undo
+description: Use only when the user explicitly invokes $gsd-path-undo. Preview and apply helper-owned undo of an unpublished checkpoint, last task landing, uncommitted ship archive, or untracked lookahead track. Never invent git reset, revert, or force-push.
+---
+
+# GSD Path Undo
+
+One invocation = one preview, then apply only after explicit user confirmation.
+The bundled [pipeline_undo.py](scripts/pipeline_undo.py) is the only undo
+authority; do not reimplement git reset in model reasoning.
+
+This skill never advances a phase gate, never force-pushes, and never rewrites
+a commit that is an ancestor of `origin/main`.
+
+## Process
+
+1. **Preview.** Run `python3 <absolute-bundled-pipeline_undo.py> preview --repo
+   <absolute-root>`. Treat the JSON as the only classification. On helper
+   error, present **Outcome** with the error, **Review** linking STATE.md when
+   it exists, and **Next** naming `$gsd-path-forensics` when the pipeline looks
+   stuck.
+2. **Blocked.** When `target.kind` is `null`, report every `target.blocked`
+   reason. **Next** is the retry named in those reasons, or `$gsd-path-forensics`.
+   Stop. Do not apply.
+3. **Confirm.** Present **Outcome** as the `target.effects` list, **Review**
+   linking STATE.md, and **Next** asking whether to apply that exact kind
+   (recommended only when `apply` is non-null) or stop. Do not apply until the
+   user confirms.
+4. **Apply.** After confirmation, run `python3 <absolute-bundled-pipeline_undo.py>
+   apply --repo <absolute-root> --kind <target.kind> --expected-head
+   <target.head>` using the preview values verbatim. A mismatch means HEAD
+   moved: rerun preview, do not invent a SHA.
+5. **Report.** **Outcome** is `status: applied` plus the new STATE phase/status.
+   **Review** links STATE.md. **Next** names `$gsd-path status` to inspect
+   without advancing.
+
+## Rules
+
+- Never run `git reset`, `git revert`, `git push --force`, or `git checkout`
+  except through this helper.
+- Never undo a ship commit, integration merge, abandon commit, or promotion
+  commit. Those are blocked findings, not apply targets.
+- A published HEAD (reachable from `origin/<STATE.branch>`) is blocked.
+- A validated pending undo journal is returned as the resumable preview target.
+  Other pending helper journals are blocked and must be resumed by their owner.

package/skills/gsd-path-undo/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "GSD Path Undo"
+  short_description: "Helper-owned undo of unpublished pipeline work"
+  default_prompt: "Use $gsd-path-undo to preview and apply helper-owned undo."
+policy:
+  allow_implicit_invocation: false

package/skills/gsd-path-undo/scripts/_common.py

@@ -0,0 +1,180 @@
+#!/usr/bin/env python3
+# gsd-path project runtime
+"""Helpers shared by the gsd-path scripts.
+
+Every consuming script binds the names it used before (for example
+``run_git = _common.run_git``) so callers and tests that patch the name on the
+consuming module keep working.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+from pathlib import Path
+from typing import Optional
+
+PIPELINE_MARKER = "gsd-path/v2"
+BOUND_BRANCH_RE = re.compile(r"^gsd-path/M(\d{3,})$")
+
+FIELD_PATTERN = re.compile(r"^(?P<key>[a-z_]+):\s*(?P<value>.*)$")
+INLINE_LIST_PATTERN = re.compile(r"^\[(?P<body>.*)\]$")
+LIST_ITEM_PATTERN = re.compile(r"^\s*-\s+(?P<value>.*)$")
+VERIFY_LEDGER_PATH = ".project/build/verify-ledger.jsonl"
+VERIFY_RESULTS = ("pass", "fail")
+VERIFY_LEDGER_SCHEMA = "gsd-path/verify-ledger/v2"
+VERIFY_BLOCK_PATTERN = re.compile(r"```bash[ \t]*\n(?P<block>.*?)```", re.DOTALL)
+
+
+def section_body(text: str, heading: str) -> Optional[str]:
+    """The text under `## <heading>` up to the next `## `, or None when absent."""
+    match = re.search(
+        rf"(?ms)^## {re.escape(heading)}\s*\n(?P<body>.*?)(?=^## |\Z)", text
+    )
+    return match.group("body") if match else None
+
+
+def task_verify_command(task_text: str) -> str:
+    """The Verify shell text, excluding the closing fence's separator newline."""
+    body = section_body(task_text, "Verify")
+    block = VERIFY_BLOCK_PATTERN.search(body) if body is not None else None
+    return block.group("block").removesuffix("\n") if block else ""
+
+
+def latest_verify_entry(entries: list, command: str, commit: str) -> Optional[dict]:
+    for entry in reversed(entries):
+        if (entry.get("schema") == VERIFY_LEDGER_SCHEMA
+                and entry["command"] == command and entry["commit"] == commit):
+            return entry
+    return None
+
+
+def verify_ledger_entries(path: Path) -> list:
+    """Parsed verify-ledger rows; raises ValueError on a malformed line."""
+    if not path.exists():
+        return []
+    return parse_verify_ledger(path.read_text(encoding="utf-8"))
+
+
+def parse_verify_ledger(text: str) -> list:
+    entries = []
+    for number, line in enumerate(text.splitlines(), start=1):
+        if not line.strip():
+            continue
+        try:
+            entry = json.loads(line)
+        except json.JSONDecodeError as error:
+            raise ValueError(f"{VERIFY_LEDGER_PATH} line {number} is not JSON: {error}") from error
+        if (
+            not isinstance(entry, dict)
+            or not isinstance(entry.get("command"), str)
+            or not isinstance(entry.get("commit"), str)
+            or entry.get("result") not in VERIFY_RESULTS
+            or not isinstance(entry.get("recorded_at"), str)
+        ):
+            raise ValueError(f"{VERIFY_LEDGER_PATH} line {number} has invalid fields")
+        entries.append(entry)
+    return entries
+
+
+def run_command(
+    *arguments: str, cwd: Optional[Path] = None
+) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        arguments,
+        cwd=cwd,
+        text=True,
+        capture_output=True,
+        check=False,
+    )
+
+
+def run_git(
+    repo: Path, *arguments: str, input: Optional[str] = None
+) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        ("git", "-C", str(repo), *arguments),
+        input=input,
+        text=True,
+        capture_output=True,
+        check=False,
+    )
+
+
+def atomic_replace(path: Path, temporary_path: Path, content: str) -> None:
+    temporary_path.parent.mkdir(parents=True, exist_ok=True)
+    descriptor = None
+    try:
+        if temporary_path.exists() or temporary_path.is_symlink():
+            temporary_path.unlink()
+        descriptor = os.open(
+            temporary_path,
+            os.O_WRONLY | os.O_CREAT | os.O_EXCL,
+            0o666,
+        )
+        handle = os.fdopen(descriptor, "w", encoding="utf-8")
+        descriptor = None
+        with handle:
+            handle.write(content)
+        os.replace(temporary_path, path)
+    finally:
+        if descriptor is not None:
+            os.close(descriptor)
+        if temporary_path.exists() or temporary_path.is_symlink():
+            temporary_path.unlink()
+
+
+def atomic_write(path: Path, content: str) -> None:
+    atomic_replace(path, path.parent / f".{path.name}.gsd-path-tmp", content)
+
+
+def strip_yaml_comment(value: str) -> str:
+    quote = None
+    previous_significant = None
+    inline_list = value.lstrip().startswith("[")
+    index = 0
+    while index < len(value):
+        character = value[index]
+        if quote == '"':
+            if character == "\\" and index + 1 < len(value):
+                index += 2
+                continue
+            if character == quote:
+                quote = None
+        elif quote == "'":
+            if (
+                character == quote
+                and index + 1 < len(value)
+                and value[index + 1] == quote
+            ):
+                index += 2
+                continue
+            if character == quote:
+                quote = None
+        else:
+            if character in {"'", '"'} and (
+                previous_significant is None
+                or (inline_list and previous_significant in {"[", ","})
+            ):
+                quote = character
+            elif character == "#" and (
+                index == 0 or value[index - 1].isspace()
+            ):
+                return value[:index].rstrip()
+        if quote is None and not character.isspace():
+            previous_significant = character
+        index += 1
+    return value.strip()
+
+
+def unquote(value: str) -> str:
+    cleaned = strip_yaml_comment(value).strip()
+    if (
+        len(cleaned) >= 2
+        and cleaned[0] == cleaned[-1]
+        and cleaned[0] in {"'", '"'}
+    ):
+        return cleaned[1:-1]
+    return cleaned