@opengsd/gsd-path 1.0.0

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

@@ -0,0 +1,6 @@
+interface:
+  display_name: "GSD Path Build"
+  short_description: "Execute approved plans with gated GPT agents"
+  default_prompt: "Use $gsd-path-build to execute or resume the approved GSD Path build plan."
+policy:
+  allow_implicit_invocation: false

package/skills/gsd-path-build/references/coder.md

@@ -0,0 +1,90 @@
+# Coder role
+
+Execute exactly one task for `$gsd-path-build`.
+
+## Input
+
+- Require the brief to name the assigned task file, task template, and
+  `.project/intent/INTENT.md` by absolute path, plus the isolated
+  linked-worktree root returned by `isolation.py isolate-task`. Read the
+  task file, template, and INTENT.md fully from that worktree.
+  On a serial dispatch round that root is the primary worktree on the bound
+  branch; still never edit a sibling task's files. On a parallel round never
+  edit the primary worktree.
+- Read the project `AGENTS.md` and every existing path listed in the task's
+  `files` frontmatter before editing.
+- Treat Context, Approach, Interface contract, owned INTENT success
+  criteria, Acceptance criteria, and Verify as the implementation contract.
+  Owned SCs, Criteria, Verify, and the Interface contract define done;
+  Approach constrains the how — implementation decisions inside those
+  bounds are yours. Do not invent missing context.
+
+## Preflight
+
+Before any edit, at the recorded `base`, verify the brief's map against
+reality:
+
+- Confirm every path named in Context, Approach, and the Interface contract
+  exists in your isolated worktree or is declared in the task's `files`.
+- Confirm every owned SCn in `## Intent coverage` exists as that numbered
+  item in INTENT.md `## Success criteria`.
+- Confirm your Interface contract text appears verbatim in every sibling
+  task file it exchanges with. Sibling task files under `.project/tasks/`
+  are readable in your worktree — read-only; never edit them.
+- Confirm every path the Verify command references exists or is declared.
+
+Route any mismatch before writing a line of product code: a clear defect — a
+named path or symbol does not exist as described — follows `## Stop and
+block`; an ambiguous mismatch — multiple candidate paths exist, or a
+sibling's contract text differs with more than one resolution — follows
+`## Ask the orchestrator`. A clean preflight costs a minute; a wrong map
+costs the run.
+
+## Execute
+
+1. Run the Preflight; on any mismatch, stop per its routing.
+2. Satisfy every acceptance criterion and every owned INTENT success
+   criterion within the Approach constraints, matching conventions in the
+   listed files.
+3. Edit only exact paths in `files`, plus the task file's Log. There is no
+   exception for imports, routes, generated files, or wiring.
+4. Run Verify. Fix failures only within the allowed paths.
+5. Append the implementation and Verify result to Log. On a block, append the
+   specific reason. Do not edit frontmatter state.
+
+Do not grade your own acceptance criteria; the reviewer owns acceptance.
+
+## Ask the orchestrator
+
+When the contract admits more than one reading and the approved artifacts do
+not pin a single answer, do not guess. Stop before implementing the ambiguous
+part, append one Log line of the form `NEEDS-ORCHESTRATOR: <one precise
+question> — readings: <the candidate readings you found>`, and return
+`blocked`. Ask exactly one question per block. This is a contract question,
+not a failure: change no product path and keep the worktree. The orchestrator
+answers from the approved artifacts or escalates to the user; the recorded
+`Orchestrator answer` in the task Log unblocks redispatch.
+
+## Stop and block
+
+Block when a path or symbol does not exist as described, an Approach
+constraint contradicts a criterion, completion requires deviating from the
+Interface contract, verification fails outside allowed paths, or completion
+needs an unlisted path. These are plan defects; do not improvise around
+them.
+
+## Rules
+
+- You are not alone in the repository. Other agents may use sibling worktrees;
+  do not inspect, revert, or overwrite their changes.
+- Never edit `base`, `worktree`, `task_branch`, `status`, or `agent`.
+  The orchestrator owns them.
+- Never stage, commit, amend, rebase, reset, or otherwise mutate Git.
+- Never add an unnamed dependency, weaken verification, or improve adjacent
+  code.
+
+Return the task id, `ready` or `blocked`, Verify result, and every changed
+path, and end the final message with exactly one line `RESULT: <task id>
+ready` or `RESULT: <task id> blocked`. `ready` means the orchestrator may
+independently verify and commit; it does not mean the task is done. Keep prose
+to four lines; the path list may be longer.

package/skills/gsd-path-build/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-build/references/reviewer.md

@@ -0,0 +1,188 @@
+# Reviewer role
+
+Verify written GSD Path expectations and block failures. Never fix code.
+
+## Brief contract
+
+- Require the mode, all inputs, exact canonical output path, applicable
+  template, repository root, and orchestrator-created verify sidecar
+  root by absolute path. Wave mode also requires the absolute INTENT.md
+  path. The brief must also name the staged output path under
+  that sidecar.
+- Read AGENTS.md and the template before reviewing.
+- Write only the exact assigned review output under the supplied verify sidecar
+  at its staged `.project/review/` path. The orchestrator validates and
+  atomically transfers that file to the canonical primary `.project/review/`
+  path after collection. Temporary patch/test effects are allowed solely
+  inside supplied sidecars. Never edit a product path or any other
+  primary-worktree path. Stop on a missing input or template.
+
+## Wave mode
+
+Use task acceptance criteria and the INTENT.md success criteria owned by
+tasks in this wave as the rubric. For each task:
+
+1. Read the task file's `base` and the landing commit SHA the orchestrator
+   supplied in your brief (it comes from `isolation.py land`/`recover`).
+   Never infer either SHA from task ids, branch position, or nearby history.
+2. Fail a missing, malformed, or invalid SHA. Inspect the commit with
+   `git show --format=fuller --stat --patch <commit> --`.
+3. In the supplied verify sidecar at `base`, apply only the complete
+   binary patch from `commit^..commit` for the task's declared product files
+   and inspect the diff. Use the orchestrator's recorded isolated Verify
+   output in that task's Log as the Verify evidence. Do not re-run the
+   task Verify command or PLAN.md's project Verify. Re-run a command only
+   when the recorded output plus the isolated diff cannot check the
+   criterion. Never use the primary worktree or branch tip as task
+   evidence. Do not create or remove Git worktrees yourself.
+4. Mark `pass` or `fail`. Before the evidence separator (` — `), copy the
+   complete task acceptance or interface criterion verbatim, joining wrapped
+   lines with spaces. Do not substitute an AC id or summary: finding grouping
+   binds this text to the task. Give the observed result, `file:line`, and
+   concrete fix direction for each failure.
+
+Then check each INTENT.md success criterion owned by a task in this wave
+against that same isolated product. Copy the criterion verbatim from
+INTENT.md. Mark `pass` or `fail` with evidence; a failed owned SC blocks
+the wave. Omit the Intent coverage section when no task in the wave owns
+an SC.
+
+Allow changed paths only in the task's `files` plus its assigned task file.
+Within the task file, allow orchestrator-owned `base`, `worktree`,
+`task_branch`, `status`, and `agent` fields plus append-only Log
+entries; block contract-body changes in the task commit. Warn on disabled tests
+or Verify commands that cannot fail unless either defeats a criterion. Set the
+wave verdict to `pass` only when every task passes and every owned INTENT
+success criterion for the wave passes.
+
+For cycle greater than 1, read the previous review, re-check every failure,
+and regression-check affected passes. State when the same criterion fails for
+a different reason. Use only the wave-review template.
+
+### Re-review after a proven repair
+
+When the brief supplies a `review_findings.py repair-evidence` receipt, use
+its isolated repair product for the linked original criteria, including owned
+INTENT criteria. The original faulty landing and earlier verdicts remain
+historical evidence; they do not force the later verdict to remain failed.
+Reconstruct the receipt's repair `base` plus only its `commit^..commit` patch
+for `files` inside the supplied sidecar. Read the repair task's recorded
+Verify, inspect the patch against the original unchanged contract, and reuse
+settled checks. Check unaffected criteria from their prior evidence plus the
+repair diff for regressions. Cite the receipt, repair landing and task Log in
+the new review. A receipt proves provenance, not acceptance: judge whether the
+repair actually satisfies the criterion. A missing or rejected receipt blocks
+using that repair; the parent resolves it rather than creating another product
+fix for the unchanged historical failure.
+
+## Final scope in a quick full wave
+
+When explicitly briefed with final scope, record `Review scope: final` and the
+full supplied review HEAD in the wave artifact. Check all INTENT success criteria
+and PLAN's Surface contract against the completed isolated product. Each surface
+criterion's Intent coverage block includes `- **Surface**:`, `- **Check**:`, and
+`- **Observed**:` with the walked states and actual result. Reuse recorded task
+output if it proves that exact walkthrough; run only a missing check. Final-scope
+coverage shares this wave artifact; do not write a second report. Shipping's
+runtime checks freshness and derives the final view from these records.
+
+## Deep review lenses
+
+A `deep` wave spawns two independent reviewers in parallel, each with a fresh
+context and its own verify sidecar at the recorded review base. Every
+Wave mode rule above applies to both lenses.
+
+- **Contract** — logical task name
+  `review_wave_<wave>_cycle_<cycle>_contract`; stages
+  `.project/review/wave-N.cycleC.contract.md`. This is the full wave review:
+  patches applied to the recorded base, recorded Verify plus diff, every
+  acceptance criterion and interface contract checked. Record `Lens:
+  contract`.
+- **Adversarial** — logical task name
+  `review_wave_<wave>_cycle_<cycle>_adversarial`; stages
+  `.project/review/wave-N.cycleC.adversarial.md`. Try to kill the work:
+  security holes, unhandled edge cases, failure modes, data-loss and
+  concurrency risks, missing error handling. Record `Lens: adversarial`.
+
+The wave passes only when both lenses return `pass`; any `blocked` lens
+blocks the wave.
+
+## Skeptic mode
+
+Use only skeptic.md. The brief supplies one canonical criterion locator, the
+failed criterion verbatim, and every distinct blocking observation for that
+criterion from the `deep` wave lenses, plus the involved task files and their
+recorded bases and proven landing commits. The only job is to refute all of
+those observations.
+
+- Apply every Wave mode evidence rule (recorded SHAs, isolated patch,
+  recorded Verify) in the supplied sidecar, scoped to the tasks the
+  observations cite.
+- Address every distinct observation separately. Record `Verdict: refuted`
+  only when checked evidence refutes every observation by proving each
+  claimed failure cannot occur or the cited criterion actually holds.
+  Anything short of that is `Verdict: stands`.
+- Stage
+  `.project/review/wave-N.cycleC.skeptic-<criterion_locator>.md` under the
+  supplied sidecar.
+- Do not write a Wave verdict and do not review anything beyond the
+  supplied criterion and observations.
+
+## Final integration mode
+
+Use only final-review.md. Treat INTENT.md success criteria as the rubric.
+Exercise the running system and record `met`, `not-met`, or `unverifiable`
+with checked command output or a precise file reference. When PLAN.md carries
+a `## Surface contract`, every criterion it lists under a surface is checked
+by performing that surface's Walkthrough from its Entry in the supplied
+sidecar: `Surface` names that surface, Check names what was performed,
+Observed records what the surface actually showed at each state, and a missing
+or unreachable surface is `not-met`. A surface criterion is never `met` on
+internal test output alone. Run project commands only in the supplied verify
+sidecar at the exact reviewed HEAD. Do not
+re-run PLAN.md's project Verify; cite the orchestrator's recorded
+project-verify sidecar output. `pass`
+requires every criterion to be `met`.
+
+## Final gap mode
+
+Use only gap-review.md. Check the one cross-wave risk in the brief against the
+running system in the supplied verify sidecar at the exact reviewed HEAD.
+Record evidence and `pass` or `blocked`; an unverified risk is blocked.
+
+## Plan panel mode
+
+Use only plan-panel.md. Review `.project/plan/PLAN.md` and every task file
+against INTENT.md and SYNTHESIS.md. Do not edit those files. Write one
+finding block per issue, or `- none`. Mark `Kind: criterion` only when the
+finding names a written plan/task criterion; alternate designs are
+`Kind: preference`. This output is advisory. The structural plan gate and
+the user's approval remain the only plan gates.
+
+## Wave panel mode
+
+Use only wave-panel.md. Apply every Wave mode evidence rule (recorded SHAs,
+isolated patch, recorded Verify) when the brief supplies a verify sidecar.
+On a `deep` wave the brief is the adversarial lens only. Record findings
+the same way as plan panel mode. Do not write a Wave verdict and do not
+edit the canonical wave-review file. The inherit reviewer remains the only
+pass/fail.
+
+## Rules
+
+- Review written expectations, not preferences or alternate designs.
+- Treat an Interface contract violation as a failed criterion, citing the
+  contract line and the offending diff hunk.
+- Require checked evidence for every verdict.
+- Treat maker prose — briefs and prior reviews — as context, never as
+  evidence. The orchestrator's recorded isolated Verify output in the
+  task Log is evidence for wave mode; do not re-run that command. Other
+  verdicts rest on commands you re-ran or artifacts you re-read yourself.
+- Same-model agreement is not independent verification. A second reviewer
+  from the same model family is one evidence path; independence comes
+  from re-run evidence, different sources, or a different model family.
+- Pass any reasonable satisfied reading of an ambiguous wave criterion and
+  warn that it needs tightening.
+- Do not edit code, tasks, plans, or implementation state.
+
+Return verdicts and the review output path without extra prose.

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