@opengsd/gsd-path 1.0.0

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

@@ -0,0 +1,167 @@
+---
+name: gsd-path-inspect
+description: Inspect an existing codebase and its documentation to establish brownfield ground truth before intent is defined. Use only when the user explicitly invokes $gsd-path-inspect or an active $gsd-path router explicitly routes to this phase.
+---
+
+# GSD Path Inspect Phase
+
+Establish ground truth about an existing project before intent is defined.
+Detect, scan, and audit first; recommend and question only after the evidence
+is on disk. Never question a user about a codebase the pipeline has not read.
+
+Routing instructions below are caller handoffs under the AGENTS.md handoff
+rule; never invoke an explicit-only sibling skill yourself.
+
+Before phase work and again before completion, apply the AGENTS.md
+pending-answer rule with the bundled `scripts/discussion_records.py`; a
+follow-up owned by inspect is resolved through its artifact gate, or the
+phase blocks.
+
+## Preconditions
+
+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
+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
+`wrote_state: false`, report the error and block without routing or claiming
+STATE.md was written.
+- `owned` — continue under the existing-state rules below.
+- `orphan` — return to `$gsd-path` for orphaned-state recovery instead of
+  initializing or overwriting it.
+- `greenfield` — the helper writes STATE.md at `define/active`; skip inspection
+  and route to `$gsd-path-define` from this returned verdict.
+- `brownfield` — require `wrote_state: true`, then continue with the helper's
+  STATE.md at `inspect/active`.
+If `.project/STATE.md` exists, run `python3 <absolute pipeline_state.py>
+validate --repo <absolute root> [--project-dir .project/next]`; a non-zero
+result returns to `$gsd-path` for ownership checking. Legal entry is
+`inspect/active|blocked`; `inspect/done` routes to define, and any later phase
+stops. When an active router supplies `.project/next/`, require its STATE.md
+to be a regular non-symlink file and apply these rules to that track state.
+When an existing state records a bound branch (single-milestone restart
+or program next-milestone), require the current symbolic branch to match and
+preserve both `branch` and `milestone`. Do not re-enter `inspect/done` in the
+same milestone; a later milestone's `inspect/active` is a new scan.
+
+## Process
+
+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
+   inventory. If STATE.md is now missing, restart Preconditions and route from
+   the new `initialize` result; never continue from an ignored result. Record
+   the SHA-256 of each existing assigned destination and preserve the existing
+   DOCS-AUDIT.md in a temporary prior-audit file; when it records an
+   `Audited HEAD` Git resolves as an ancestor of HEAD, freeze the changed set
+   as `$gsd-path-docs-audit` step 1 describes. Preserve an existing
+   router-bound branch and milestone.
+2. Dispatch two independent agents in parallel, following the local
+   [runtime dispatch contract](references/dispatch.md) and its deterministic
+   task-name rules:
+   - **Codebase mapper** — role
+     [codebase-mapper](references/codebase-mapper.md), template
+     [codebase](templates/codebase.md), output
+     `.project/research/evidence-codebase.md` (`.project/next/research/` in
+     Lookahead mode), task name `inspect_codebase`.
+   - **Docs auditor** — role
+     [docs-auditor](references/docs-auditor.md), template
+     [docs-audit](templates/docs-audit.md), output
+     `.project/research/DOCS-AUDIT.md` (same next/ prefix in Lookahead mode),
+     task name `inspect_docs`.
+   Give each the absolute repo root and exclusion rule. Give the auditor the
+   exact frozen inventory, the changed set when one exists, and `alignment
+   mode: false`; it audits only that
+   list and never rediscovers paths. The frozen inventory travels inside the
+   dispatch brief; never persist it as a `.project/` sidecar file. Pass an existing DOCS-AUDIT.md separately
+   as carry-forward input so its `## User rulings` and `planned` values remain
+   verbatim. When Git has a resolvable HEAD and no non-`.project` worktree
+   changes, the orchestrator creates a verify sidecar for each agent with
+   `python3 <absolute isolation.py> isolate-verify --repo <absolute primary>
+   --base <HEAD> --name inspect-codebase` and `--name inspect-docs`, and
+   includes its path and revision for project commands; expected new pipeline
+   artifacts do not make product code dirty. Each agent writes only its
+   assigned output under that sidecar and keeps it there for the gates in step
+   3. Otherwise no
+   project command may run. The docs-auditor brief carries current HEAD as the
+   audit baseline only when its verify sidecar was created at HEAD; otherwise
+   it carries `none`. The auditor writes that baseline as `Audited HEAD`.
+3. Gate both artifacts against their templates: the codebase evidence needs
+   a filled `## Map` plus findings as observed — no quota, but an empty
+   findings section must say why; the docs audit must pass the bundled
+   `python3 <absolute check_docs_audit.py> --repo <docs sidecar> --audit
+   <track-relative DOCS-AUDIT.md> --inventory <frozen inventory file>`, where
+   the audit path is `.project/research/DOCS-AUDIT.md` normally and
+   `.project/next/research/DOCS-AUDIT.md` in Lookahead mode; add
+   `--prior-audit <temporary prior-audit file>` when one was preserved and
+   `--changed <temporary changed-set file>` when one was frozen
+   (disjoint `## Doc:` sections and `## Descriptive docs` equal to the frozen
+   inventory, every claim a valid verdict with evidence, Summary counts and
+   remediation queue consistent). After each artifact passes, collect it with
+   `python3 <absolute isolation.py> collect-artifact --repo <absolute primary>
+   --source <returned worktree> --base <recorded HEAD> --branch <returned
+   branch> --source-path <assigned track-relative path> --destination-path
+   <assigned track-relative path>`, adding `--expected-destination <recorded
+   prior SHA-256>` when that destination existed. Require the returned base,
+   branch, source, and destination to match. Only then retire with `python3
+   <absolute isolation.py> retire --repo <absolute primary> --worktree
+   <returned worktree> --branch <returned branch>` without `--force`.
+   Redispatch one complete corrected brief under the same logical task
+   name, following the runtime dispatch contract. If it still fails, run
+   `pipeline_state.py transition` with expected `inspect/active`, the exact
+   current branch and archive values, `--set-status blocked`, and an event
+   naming the failed artifact gate. Present **Outcome** with the failed gate, **Review**
+   linking each malformed output that exists or STATE.md when an output is
+   missing, and **Next** naming the one correction or user decision required;
+   then stop.
+4. Present the ground truth to the user, brief — a summary, not a dump:
+   - what the project is (stack, architecture, entry points, maturity);
+   - what demonstrably works (verified claims, passing verifies);
+   - drift: what the docs claim that the code contradicts, and what exists
+     with no documentation at all;
+   - the mapper's open questions about apparent intent.
+   Lead with the outcome, then provide absolute-path Markdown links to the
+   track's `research/evidence-codebase.md` and `research/DOCS-AUDIT.md`
+   (`.project/research/` normally, `.project/next/research/` in Lookahead
+   mode), then state that define is next.
+5. Run `python3 <absolute pipeline_state.py> transition --repo <absolute root>
+   [--project-dir .project/next]
+   --event "inspection artifacts passed" --expect-phase inspect --expect-status
+   active --expect-milestone <current milestone or null> --expect-branch
+   <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.
+
+## Lookahead mode
+
+Entered only when an active router supplies the lookahead track root
+`.project/next/` while the active STATE.md is `build/active` in program
+flow. Evaluate every state and artifact precondition against the track:
+`.project/next/STATE.md` is the state file and the outputs are
+`.project/next/research/evidence-codebase.md` and
+`.project/next/research/DOCS-AUDIT.md`. Freeze the inventory from the
+repository root as usual. Carry forward the active
+`.project/research/DOCS-AUDIT.md` when it exists so its `## User rulings`
+and `planned` values remain verbatim; otherwise carry forward a track-local
+audit if present. Never write an active-path artifact.
+
+## Rules
+
+- Scanning is read-only. Inspection changes nothing outside `.project/`.
+- Project commands run only in agent-specific disposable verification
+  worktrees at a recorded clean revision; otherwise checks use static evidence
+  or are `unverifiable`. They never run in the source worktree.
+- Report reality, not judgment: "tests exist but 3 fail" — never "test
+  hygiene is poor". The user may know exactly why those 3 fail.
+- Doc-vs-code conflicts are surfaced, never auto-resolved; whether the doc
+  or the code is wrong is the user's ruling, captured while defining intent.
+- Inspection evidence feeds the whole pipeline: researchers treat
+  `evidence-codebase.md` as a fifth standard dimension when it exists, the
+  planner must match its conventions, and reviewers may cite it.

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

@@ -0,0 +1,6 @@
+interface:
+  display_name: "GSD Path Inspect"
+  short_description: "Establish existing-project ground truth"
+  default_prompt: "Use $gsd-path-inspect to inspect this existing project before defining intent."
+policy:
+  allow_implicit_invocation: false

package/skills/gsd-path-inspect/references/codebase-mapper.md

@@ -0,0 +1,52 @@
+# Codebase mapper role
+
+Map an existing codebase into evidence the pipeline can build on. Read-only:
+change nothing outside your single output file.
+
+## Input and output
+
+- Require the absolute repo root, exclusion rule, output path, and absolute
+  codebase-template path.
+- Read AGENTS.md and the template before scanning. Stop on a missing path.
+- Write only the assigned output using the template. When the brief supplies a
+  disposable root, write the output under that root at the relative handoff
+  path; the orchestrator transfers it after validation. Do not ask the user
+  questions.
+
+## What to establish
+
+Fill the template's `## Map` from direct inspection — manifests, lockfiles,
+entry points, directory structure, CI config, test layout — never from the
+docs' description of them (the docs auditor checks those separately):
+
+- stack and versions actually in use;
+- architecture shape: entry points, layers, how a request/run flows;
+- conventions: naming, error handling, test style, commit style;
+- maturity: what runs, what the tests cover, what is scaffolding;
+- activity: recent git history — where the work has been happening.
+
+Then report findings to the evidence standard: claim, source (file:line or
+command actually run), confidence, and why it matters to inspection. Give
+special weight to:
+
+- **load-bearing surprises** — things a planner would guess wrong from the
+  docs alone;
+- **half-built areas** — code that exists but is unreachable, unused, or
+  failing;
+- **apparent intent** — what the project seems to be trying to become,
+  flagged as inference, with the open questions a define session should put
+  to the user.
+
+## Rules
+
+- Build, test, lint, and help commands are not presumed read-safe. Never run a
+  project command in the source worktree. Run it only in the pre-created,
+  agent-specific verify sidecar named in the brief at its recorded clean
+  Git revision. Do not create or remove Git worktrees yourself. If no faithful
+  sidecar revision is supplied, use static evidence or record the check as
+  `unverifiable`. Never run deploy, publish, or migration commands.
+- Observations, not judgments: "3 of 40 tests fail (list)" — not "poor
+  test hygiene". The user may know exactly why.
+- Unreadable or ambiguous areas are findings too — say what blocked you.
+- Return a brief structured summary: the output path, finding count, and the
+  single biggest surprise.

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

@@ -0,0 +1,60 @@
+# Docs auditor role
+
+Verify that the project's Markdown documentation matches what the project
+actually does. Read-only: change nothing outside your single output file.
+
+## Input and output
+
+- Require the absolute repo root, exclusion rule, output path, absolute
+  docs-audit-template path, whether alignment mode applies, and a frozen,
+  sorted Markdown inventory.
+- Read AGENTS.md and the template before auditing. Stop on a missing path.
+- Write only the assigned output using the template. When the brief supplies a
+  disposable root, write the output under that root at the relative handoff
+  path; the orchestrator transfers it after validation. Do not ask the user
+  questions.
+
+## Method
+
+1. **Inventory** uses the supplied frozen path list verbatim; never rediscover
+   paths after dispatch. If a standalone brief omitted a list, snapshot once
+   before writing and exclude the assigned output. Every listed file is
+   accounted for exactly once: a doc with at least one testable claim gets
+   its own `## Doc:` section; a doc with none gets one line in the
+   `## Descriptive docs` list — never its own section, never skipped.
+2. **Extract claims** — statements reality can contradict: commands,
+   features, structure, status/checkboxes, config, integrations.
+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:
+   - `verified` — checked and true
+   - `stale` — plausibly once true; the code has moved on
+   - `aspirational` — describes something never built
+   - `unverifiable` — not checkable from the repo; say what would be needed
+   When the brief supplies a changed set, carry a prior `verified` row with
+   exactly one `unchanged: ` prefix on its Evidence only when it is not a
+   command claim and neither its doc nor any path its evidence names is in
+   that set. Copy an already-carried row verbatim without adding another
+   prefix. Re-verify every other claim. No changed set means no carried rows.
+4. **Alignment mode** (when `.project/` artifacts exist): also check
+   INTENT success criteria against reality, `status: done` tasks against
+   their `isolation.py recover`-proven landing SHA and a re-run of their Verify command,
+   SYNTHESIS decisions against the code's actual stack and shape, and
+   STATE against task frontmatter. Same verdicts, same evidence bar.
+5. **Classify remediation** for every non-verified claim: `fix-doc`,
+   `fix-code`, or `NEEDS-USER` when the right side of the conflict is not
+   yours to decide.
+
+## Rules
+
+- Hold your own output to the standard you enforce: a verdict without
+  recorded evidence is a defect.
+- Build, test, lint, and help commands are not presumed read-safe. Never run a
+  project command in the source worktree. Run it only in the pre-created,
+  agent-specific verify sidecar named in the brief at its recorded clean
+  Git revision. Do not create or remove Git worktrees yourself. Otherwise use
+  static evidence or mark the claim `unverifiable`. Never deploy, publish,
+  migrate, or mutate external state.
+- Contradictions between two docs are findings; report both sides.
+- Return the output path, verdict counts, and the worst drift found in at
+  most three lines.

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