@opengsd/gsd-path 1.0.0

package/skills/gsd-path-research/templates/evidence.md

@@ -0,0 +1,24 @@
+# Evidence — <dimension>
+
+<!-- Written by one researcher role. Consumed by the decider. -->
+
+Dimension: <domain | stack | pitfalls | similar | custom>
+Questions assigned: <exact RESEARCH questions joined by "; ", or "none">
+
+## Finding: <short claim as heading>
+
+- **Claim**: <one specific, falsifiable statement>
+- **Source**: <URL / doc / repo path actually opened>
+- **Confidence**: <high | medium | low>
+- **Why it matters here**: <one line tying this to INTENT.md>
+
+<!-- One block per load-bearing finding — no quota. Repeat as needed. -->
+
+## Assigned questions — answers
+
+- <question> → <answer with source, or "no reliable source found">
+
+## Dead ends
+
+<!-- What was checked and didn't pan out, so nobody re-treads it. -->
+- <path explored> — <why it's a dead end>

package/skills/gsd-path-research/templates/research-handoff.md

@@ -0,0 +1,25 @@
+# Research Handoff
+
+<!-- Written by the research orchestrator and consumed by decide. -->
+
+Phase: research
+Status: complete
+Intent: `.project/intent/INTENT.md`
+<!-- Program flow (no milestone INTENT exists): write the Intent line as
+     `.project/CHARTER.md` instead — the validator accepts exactly one of the
+     two paths, matching the file that actually exists. -->
+
+## Dispatch
+
+<!-- Include every standard dimension exactly once. A custom dimension may
+     supplement these rows, never replace a standard row. -->
+- `domain` — dispatched → `.project/research/evidence-domain.md` — <why this dimension ran>
+- `stack` — skipped → none — <why this dimension was skipped>
+- `pitfalls` — skipped → none — <why this dimension was skipped>
+- `similar` — skipped → none — <why this dimension was skipped>
+
+## Question assignments
+
+<!-- Copy every [RESEARCH] question from INTENT.md exactly once. Use `- none`
+     only when INTENT.md has no [RESEARCH] questions. -->
+- `[RESEARCH] <question copied from INTENT.md>` → `domain`

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

@@ -0,0 +1,215 @@
+---
+name: gsd-path-roadmap
+description: Slice an approved GSD Path program charter into a dependency-ordered roadmap of independently shippable milestones. Use only when the user explicitly invokes $gsd-path-roadmap or an active $gsd-path router explicitly routes to this phase.
+---
+
+# GSD Path Roadmap Phase
+
+Dispatch one roadmapper, gate its roadmap, and obtain the single approval that
+authorizes milestone planning. Rolling-wave: the roadmap scopes every
+milestone; waves and tasks belong to `$gsd-path-plan`.
+
+Routing instructions below are caller handoffs under the AGENTS.md handoff
+rule; never invoke an explicit-only sibling skill yourself.
+
+Before dispatch and again before approval, apply the AGENTS.md
+pending-answer rule with the bundled `scripts/discussion_records.py`; a
+follow-up owned by roadmap is resolved in ROADMAP.md, or the phase blocks.
+
+## Preconditions
+
+Require `pipeline_state.py validate --repo <absolute root>` to pass; otherwise
+return to `$gsd-path` for ownership checking. Legal entry is
+`decide/done` with an existing `.project/CHARTER.md` and no `.project/ROADMAP.md`
+yet, `roadmap/active|blocked`, or a
+milestone-boundary re-slice: `inspect/active` or `define/active` with no
+approved INTENT.md for the next milestone and a user request to re-scope the
+remaining `pending` entries,
+or `roadmap/active` with STATE.milestone null and an `abandoned` entry in
+ROADMAP.md (the post-abandon re-slice the build orchestrator hands off).
+Enter from `decide/done` only with `pipeline_state.py transition`, exact
+expected phase/status/milestone/branch/archive fields, event `roadmap started`,
+and `--set-phase roadmap --set-status active`; never edit STATE directly. In a
+milestone-boundary re-slice, preserve the entering `inspect/active` or
+`define/active` state throughout the re-slice.
+Any later phase blocks; mid-milestone
+re-scope is never legal — finish or ship the active milestone first. A
+`decide/done` state with ROADMAP.md already present is milestone-scope decide;
+route to `$gsd-path-plan`, never regenerate the roadmap beneath it. Absent
+CHARTER.md, this is not a program: route to `$gsd-path`, which continues the
+single-milestone flow at plan. Before dispatching every re-slice, run the
+bundled `scripts/promote_lookahead.py snapshot-roadmap --roadmap
+.project/ROADMAP.md --snapshot .project/ROADMAP.before-reslice.md` helper.
+Create the baseline once and retain it through every revision; an `existing`
+result is recovery evidence and must never be replaced from the current
+candidate. When `.project/next/` holds a lookahead track, also save its
+milestone slug. Do not ask for the keep/discard ruling until the candidate
+roadmap has been generated and passed its gate.
+
+Require `.project/CHARTER.md` and `.project/SYNTHESIS.md` (program scope) with
+a non-empty `## Decisions` or `## Settled` section and no unresolved
+`NEEDS-USER` items before dispatch. Route to the producing phase when a
+precondition fails.
+
+## Process
+
+1. Read the local [roadmap template](templates/roadmap.md) and resolve it to an
+   absolute path.
+2. Read the local [roadmapper role](references/roadmapper.md), then follow the
+   local [runtime dispatch contract](references/dispatch.md) with deterministic
+   logical task name `roadmap` and a `heavy` tier hint. Give it absolute role,
+   `AGENTS.md`, `WORKFLOW.md`, CHARTER.md, SYNTHESIS.md, every dispatched
+   evidence file named in `.project/research/RESEARCH.md` — after milestone
+   archival has moved the active research directory, name the read-only
+   archived manifest and evidence copies under their
+   `.project/archive/<NNN>-<slug>/research/` paths
+   instead — template, and output
+   paths, including `.project/LESSONS.md` when it exists. On a re-slice, also
+   give `.project/ROADMAP.before-reslice.md` with the instruction to preserve
+   `shipped` entries byte-for-byte except Status/Archive/Integrated fields and
+   to never modify `abandoned` entries at all. For a milestone-boundary
+   re-slice, also preserve the existing `active` entry byte-for-byte; only
+   `pending` entries are in scope.
+   The output is exactly `.project/ROADMAP.md` — no other location is
+   canonical.
+3. Gate ROADMAP.md:
+   First run `python3 <absolute check_handoffs.py> roadmap --repo <absolute
+   root>`; its structural result is required in addition to the semantic
+   checks below.
+   - Every CHARTER.md `Full scope: in` item maps to at least one milestone,
+     and every milestone traces back to charter scope.
+   - Every milestone entry has Goal, Depends on, Surfaces, Status, Archive,
+     Scope in/out, Success criteria, Risks, and Open questions fields; ids are
+     unique and ordered.
+   - Every milestone whose Surfaces is not `none` has at least one success
+     criterion observable at each named surface. A milestone that delivers
+     something a person uses never carries `Surfaces: none`.
+   - Dependencies reference earlier milestone ids and form an acyclic graph.
+   - M001 is the thinnest end-to-end skeleton that burns the riskiest
+     synthesis decisions.
+   - Rolling-wave: no waves, tasks, or file lists anywhere in the roadmap.
+   - No scope-out veto appears in any milestone; every synthesis decision is
+     honored by at least one milestone's scope.
+   - On a re-slice, `shipped` entries differ from
+     `.project/ROADMAP.before-reslice.md` only in Status/Archive/Integrated;
+     `abandoned` entries are byte-for-byte identical.
+   - On a milestone-boundary re-slice, the prior `active` entry is byte-for-byte
+     identical to `.project/ROADMAP.before-reslice.md`.
+4. Redispatch one complete corrected brief under logical task name `roadmap`,
+   following the runtime dispatch contract and including all gate failures.
+   Allow one revision round. If it still fails, keep the entering
+   `inspect/active` or `define/active` state for a milestone-boundary re-slice
+   and use `pipeline_state.py transition` with that complete state as both the
+   expected and retained state and an event naming the failed roadmap gate.
+   Otherwise use the helper with expected `roadmap/active`, exact milestone,
+   branch, and archive values, `--set-status blocked`, and the same event. Then
+   present **Outcome** with the failed gate, **Review** linking the resolved
+   absolute ROADMAP.md path (or STATE.md when ROADMAP.md is missing), and
+   **Next** naming the one correction or user decision required. Stop.
+5. On a re-slice with a saved lookahead track, run the bundled
+   `scripts/promote_lookahead.py compare-entry --before
+   .project/ROADMAP.before-reslice.md --after .project/ROADMAP.md --milestone
+   <lookahead-slug>` helper now. When STATE.milestone is set, append
+   `--active-milestone <STATE.milestone>`; when it is unset, omit that option.
+   It compares every plan-binding part of the entry while ignoring only
+   Status, Archive, and Integrated, and requires that entry to remain the
+   candidate roadmap's first dependency-ready milestone. When it returns
+   `status: unchanged`, ask
+   the user to choose
+   `Keep the unchanged lookahead track (recommended)` or `Discard and
+   regenerate the lookahead track`. When it returns `status: changed`, offer
+   `Discard and regenerate the lookahead track (recommended)` or `Request
+   roadmap changes`; keeping the stale track is not valid. Apply the ruling
+   and record the helper result and ruling with `pipeline_state.py transition`,
+   expecting and retaining the complete entering state with event `lookahead
+   re-slice ruling: <ruling>`; never append it directly. Retain the baseline
+   through any requested roadmap revisions and the final approval decision.
+6. On a post-abandon re-slice, first run the bundled
+   `scripts/promote_lookahead.py select-next --roadmap .project/ROADMAP.md`
+   helper against the gated candidate. When it returns `status: complete`,
+   report program completion against CHARTER.md's program success criteria and
+   stop without offering a pending-milestone approval. When it returns
+   `status: selected`, use only its exact milestone in the approval and
+   transition below. A `status: none` result blocks without mutation.
+   Show every milestone id, goal, and dependency summary as the outcome. Link
+   the resolved absolute `.project/ROADMAP.md` path, then ask one explicit next
+   question. For a milestone-boundary re-slice, list `Approve roadmap and
+   resume the active milestone (recommended)` first. For a post-abandon
+   re-slice, list
+   `Approve roadmap and inspect <selected-milestone> (recommended)` first.
+   Otherwise list `Approve roadmap and start the first
+   pending milestone (recommended)` first. In every case, list `Request
+   changes` as the alternative. If the user requests changes,
+   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:
+
+   ```text
+   python3 <absolute pipeline_state.py> approve \
+     --repo <absolute root> --kind roadmap \
+     --milestone <selected first pending 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.
+
+## Rules
+
+- Cover the charter exactly: no unmapped scope, no unscoped milestones.
+- Milestone granularity only; never drift into waves, tasks, or file scopes.
+- Every milestone must be shippable on its own stated dependencies.
+- Surface scope cuts as `NEEDS-USER`; never drop charter scope silently.

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

@@ -0,0 +1,6 @@
+interface:
+  display_name: "GSD Path Roadmap"
+  short_description: "Slice a program charter into a milestone roadmap"
+  default_prompt: "Use $gsd-path-roadmap to slice an approved program charter into dependency-ordered milestones."
+policy:
+  allow_implicit_invocation: false

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

@@ -0,0 +1,131 @@
+# Shared Agent Skills dispatch
+
+Apply this contract whenever a GSD Path skill delegates work from the shared
+`~/.agents/skills` bundle. Inspect the advertised child-agent tool schema and
+use exactly one matching branch:
+
+- A `spawn_agent` tool exposing `task_name`, `agent_type`, and `fork_turns` is
+  Codex. Use `fork_turns: "none"`; coders use the built-in `worker` type and
+  every other role uses `default`. Reuse a completed logical target with
+  `followup_task`. For Codex reasoning effort, use `high` for the portable
+  `heavy` tier and `low` for the portable `light` tier; leave reasoning effort
+  unset for the session-default tier, and never pass `heavy` or `light` as a
+  literal Codex value.
+- A `spawn_agent` tool without those Codex fields is Zed. Spawn one isolated,
+  full-capability child per brief. Zed children are not resumable, so retries
+  use a fresh child and a complete prompt.
+- An `invoke_subagent` tool advertising `TypeName`, `Workspace`, and `Role` is
+  Antigravity. Use `TypeName: self`, the exact supplied root as `Workspace`,
+  and the logical task name as `Role`. Keep the returned child ID and use
+  `send_message` for follow-up work when available; otherwise start a fresh
+  child with the complete prompt.
+- A `spawn_subagent` tool advertising the `general-purpose` type is Grok. Use
+  `subagent_type: general-purpose`, `capability_mode: all`, the exact supplied
+  root as `cwd`, `isolation: none`, and `background: true`. Supply the logical
+  task name as `description`, keep the returned ID, and use `resume_from` with
+  the complete new prompt for later work. Wait for a colliding active child and
+  collect results with `wait_commands_or_subagents`.
+- A `Task` tool advertising the custom `gsd-path` subagent is Cursor. Use that
+  model-inheriting, full-capability child. Resume it by returned agent ID when
+  available; otherwise retry with a fresh child and a complete prompt.
+- A `Task` tool advertising the built-in `general` subagent is OpenCode. Use
+  that child; if an installed OpenCode v2 host exposes the renamed `subagent`
+  tool instead, use its advertised schema with the built-in `general` agent.
+  Supply the logical task name as the child description. Reuse a returned
+  child-session ID only when the host advertises a resume parameter; otherwise
+  use a fresh `general` child and the complete prompt.
+- A `task` tool advertising the `general-purpose` child is GitHub Copilot CLI.
+  Use that child. Keep its returned ID for follow-up while the host exposes
+  it; otherwise retry with a fresh child and a complete prompt.
+- An `invoke_sub_agent` tool with a `general-purpose` subagent is Kiro. Use
+  that child for every role; there is no worker/default type split. Start a
+  fresh general-purpose child for every correction, retry, post-patch review,
+  repeated audit, or later milestone — Kiro subagents are not resumable and
+  disk artifacts are the source of truth. Supply the logical task name as the
+  task description. Set the child working directory to the exact repository or
+  linked-worktree root supplied by GSD Path; do not ask Kiro or the child to
+  create another worktree. Encode task dependencies explicitly; launch
+  independent children concurrently up to the host's advertised
+  concurrent-subagent capacity.
+
+For every branch:
+
+- Supply the deterministic logical task name: `inspect_codebase`,
+  `inspect_docs`, `docs_audit`, `research_<dimension>`, `decide`, `roadmap`,
+  `plan`,
+  `plan_patch`, `build_<task_id>`, `review_wave_<wave>_cycle_<cycle>`
+  (a `deep` wave review appends the lens suffix `_contract` or
+  `_adversarial`; an optional review panel uses
+  `review_wave_<wave>_cycle_<cycle>_panel_<family>`; an optional finding
+  skeptic uses `review_wave_<wave>_cycle_<cycle>_skeptic_<criterion_locator>`),
+  `review_plan_panel_<family>`,
+  `review_final`, or `review_gap_<number>`. Normalize variable parts to
+  lowercase ASCII and replace non-alphanumeric runs with one underscore.
+  Never add a random suffix or collide with a running logical target.
+- Resolve the phase's linked role brief to an absolute path, include it in the
+  prompt, and require the child to read it before acting. The role brief
+  supplies the read-only boundary for auditors and reviewers.
+- Tier hints: use the portable `heavy` tier for `plan`, `plan_patch`, `decide`,
+  and `roadmap`, the portable `light` tier for `inspect_docs` and `docs_audit`,
+  and the session-default tier for every other role. Apply the Codex mapping
+  above when its schema advertises reasoning-effort selection. On every other
+  host, use only an exact native equivalent advertised by that host; otherwise
+  do not override the model or reasoning effort. The only exception is a
+  review-panel child: when the host advertises model selection, pass the exact
+  slug returned by `scripts/review_panel.py resolve` for that family. Never
+  override the model on the canonical reviewer, planner, coder, or any other
+  role.
+  Host isolation: none. The child's working directory is the exact absolute
+  root GSD Path supplied; a host SHA checkout or extra worktree is a contract
+  failure. Never ask the host to create a worktree. Give the child the exact
+  repository or linked-worktree root supplied by GSD Path.
+- Send a self-contained prompt with absolute input, template, and output paths
+  plus the child's bounded responsibility. Every brief also names the absolute
+  `AGENTS.md` and `WORKFLOW.md` paths (or explicitly says they are absent), the
+  next phase that consumes the output, the gate it must satisfy, and the
+  terminal result it must return. A coder prompt also names its isolated
+  linked-worktree root; no child may infer the primary worktree.
+- The parent is the sole dispatcher and lifecycle owner. If the runtime exposes
+  structured Run/Task/Dispatch orchestration, bind one Run, create one Task per
+  independent brief with explicit dependencies, inject the brief, and wait for
+  every `worker_done`, `escalation`, or question before applying the gate.
+  Verify the task and dispatch records before reporting the work as
+  orchestrated. On runtimes without that layer, use the host adapter's
+  equivalent and preserve the same logical name, completion state,
+  timeout/cancellation, and cleanup rules; never silently delegate again from a
+  child.
+- When the structured layer exposes a blocking ask/reply channel, route a
+  coder's `NEEDS-ORCHESTRATOR` question through it as a live question with
+  the worker held alive for the reply, instead of block-and-redispatch. The
+  answer is still appended to the task Log as
+  `Orchestrator answer:` so the portable on-disk record stays complete, and a
+  timed-out or unavailable channel falls back to the portable block path.
+- A child that receives a disposable worktree stages its assigned artifact
+  under that root. The parent validates it and atomically transfers it to the
+  canonical project path before removing the exact disposable root. A child
+  never writes a disposable-review output directly into the primary worktree.
+- Launch independent briefs concurrently up to the advertised child capacity,
+  batch any remainder without combining briefs, and collect every result
+  before applying the phase gate. Do not leave an active child, logical task, or
+  temporary worktree after collection; a timeout or cancellation is a blocked
+  result, not a silent success.
+- If the tool schema is ambiguous or the required full-capability child is
+  unavailable, stop and report the missing capability. Do not guess the host
+  or silently collapse an independence boundary into the main context.
+
+## Configured output budgets
+
+When the owner supplies token budgets, use the router bundle's
+`scripts/token_budget.py` with the owner's exact task and session values and
+quoted authority. Keep one ledger outside the worktree under the Git common
+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.
+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
+advertised hard output cap; report that limitation once. If the owner requires
+hard generation enforcement, use `admit --require-hard-cap`; unsupported means
+blocked, not budget compliance. Other hosts require a verified native counter
+and cap adapter before any enforcement claim.

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

@@ -0,0 +1,48 @@
+# Roadmapper role
+
+Slice an approved program charter into a dependency-ordered roadmap of
+independently shippable milestones. You scope; you do not plan tasks.
+
+## Input and output
+
+- Require absolute paths for CHARTER.md, SYNTHESIS.md, the roadmap template,
+  and every dispatched evidence file listed in RESEARCH.md. Read all of them,
+  plus AGENTS.md and `.project/LESSONS.md` when supplied; do not repeat a
+  recorded slicing defect.
+- Write only `.project/ROADMAP.md` using the supplied template. Stop on a
+  missing input or template.
+
+## Authority
+
+- Charter vetoes, constraints, and corrections are hard limits.
+- Synthesis decisions are settled. Surface conflicts; never average.
+- Existing evidence informs scope; do not re-research.
+
+## Slicing rules
+
+1. Cover everything: every `Full scope: in` item maps to at least one
+   milestone, and every milestone traces to charter scope. Unmappable work is
+   a scope cut — list it under the roadmap's owning milestone `Scope: out`
+   with the reason, or escalate as `NEEDS-USER`.
+2. Milestone 1 is the thinnest end-to-end program skeleton that proves the
+   riskiest synthesis decisions. Order the rest by dependency, then value.
+3. Every milestone is independently shippable: its success criteria hold with
+   only its `Depends on` milestones shipped.
+4. Rolling-wave: milestone granularity only. No waves, no tasks, no file
+   lists — planning owns those for the active milestone.
+5. Prefer the fewest milestones that respect dependencies and risk isolation;
+   each milestone costs a full plan-build-ship cycle.
+6. Put anything that would invalidate later slicing in the earliest milestone
+   that can answer it, and record it under that milestone's `Open questions`
+   so milestone-scoped research runs before its planning.
+7. Keep the dependency graph acyclic; depend on earlier milestone ids.
+8. Set `Surfaces:` on every milestone: the screens, commands, or endpoints a
+   person touches to get that milestone's outcome, or `none` when nobody
+   touches it directly. Each named surface needs a success criterion
+   observable there. Never defer a milestone's own surface to a later
+   milestone — that leaves an unusable slice, not a shippable one.
+
+## Return
+
+Return milestone count, the M001 goal, and every `NEEDS-USER` scope cut in at
+most five lines.

package/skills/gsd-path-roadmap/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