@opengsd/gsd-path 1.0.0

package/skills/gsd-path-inspect/templates/codebase.md

@@ -0,0 +1,46 @@
+# Evidence — codebase
+
+<!-- Written by the codebase mapper during $gsd-path-inspect. Read by define
+     (brownfield mode), researchers (fifth standard dimension), the planner
+     (conventions are binding), and reviewers. -->
+
+Repo root: <absolute path>
+Scanned: <date>
+Checks run: <exact commands run and their results, e.g. `npm test` → 37/40 pass>
+
+## Map
+
+- **Stack**: <languages, frameworks, versions actually in use, from manifests>
+- **Entry points**: <binaries, main modules, routes — how this thing starts>
+- **Architecture**: <layers and flow in 3–5 sentences>
+- **Conventions**: <naming, error handling, test style, commit style — binding on the planner>
+- **Maturity**: <what runs, test coverage shape, what is scaffolding>
+- **Recent activity**: <where the last N commits cluster — what was being worked on>
+
+## Finding: <short claim as heading>
+
+- **Claim**: <one specific, falsifiable statement about this codebase>
+- **Source**: <file:line or command actually run>
+- **Confidence**: <high | medium | low>
+- **Why it matters here**: <what inspection/planning gets wrong without this>
+
+<!-- Record every load-bearing surprise or half-built area observed. There is
+     no minimum finding quota; explain an empty section if none were found. -->
+
+## Apparent intent
+
+<!-- Inference, clearly flagged — what the project seems to be becoming. -->
+
+- <inference> — based on <evidence>
+
+## Open questions for define
+
+<!-- What only the user can settle about this codebase. -->
+
+- <question>
+
+## Blocked areas
+
+<!-- What could not be inspected and why. "none" if clean. -->
+
+- <area> — <what blocked inspection>

package/skills/gsd-path-inspect/templates/docs-audit.md

@@ -0,0 +1,69 @@
+# Docs Audit
+
+<!-- Written by the docs auditor ($gsd-path-docs-audit or $gsd-path-inspect).
+     Every verdict carries evidence; a verdict without evidence is a defect. -->
+
+Repo root: <absolute path>
+Audited: <date>
+Audited HEAD: <40-hex commit the claims were checked at, or none>
+Alignment mode: <yes | no — yes when .project/ artifacts were also audited>
+
+## Summary
+
+| Verdict | Count |
+|---------|-------|
+| verified | <n> |
+| stale | <n> |
+| aspirational | <n> |
+| unverifiable | <n> |
+| descriptive docs (no testable claims) | <n> |
+
+Worst drift: <one sentence — the most misleading claim found>
+
+## Doc: <path/to/doc.md>
+
+| Claim | Type | Verdict | Evidence |
+|-------|------|---------|----------|
+| "<claim, short-quoted>" | command \| feature \| structure \| status \| config \| integration | verified \| stale \| aspirational \| unverifiable | <file:line or command → result> |
+
+<!-- One section per doc that has at least one testable claim. Docs without
+     testable claims go in the Descriptive docs list below, never in their
+     own section. Evidence with exactly one `unchanged: ` prefix marks a row
+     carried from the prior audit under the role's delta rule. Copy an
+     already-carried row verbatim without adding another prefix. -->
+
+## Descriptive docs
+
+<!-- Every inventoried doc with no testable claims, one path per line.
+     The union of this list and the Doc section paths must equal the frozen
+     inventory exactly. -->
+
+- <path/to/doc.md>
+
+## Alignment (alignment mode only)
+
+- **INTENT success criteria**: <each → met so far | not yet | contradicted, with evidence>
+- **Done tasks**: <each status:done task → recover-proven landing SHA? Verify re-run result?>
+- **SYNTHESIS decisions**: <each → code conforms? evidence>
+- **STATE vs frontmatter**: <agree | discrepancies listed>
+
+## User rulings
+
+<!-- Appended after the ruling walk (standalone runs). Verbatim, append-only.
+     accept-drift rulings suppress the item in future audits.
+     `planned: no` rows are the alignment queue: $gsd-path and $gsd-path-plan offer
+     to absorb them until drained. When a ruling becomes a task, set
+     planned to the task id — never delete the row. -->
+
+| Queue # | Ruling | User's words | Planned |
+|---------|--------|--------------|---------|
+| 1 | fix-code \| fix-doc \| accept-drift | "<verbatim>" | no \| <task id> \| n/a (accept-drift) |
+
+## Remediation queue
+
+<!-- Every non-verified claim, classified. The user rules on this queue;
+     the auditor never fixes anything. -->
+
+| # | Doc | Claim | Verdict | Class | Suggested action |
+|---|-----|-------|---------|-------|------------------|
+| 1 | <doc> | <claim> | stale | fix-doc \| fix-code \| NEEDS-USER | <one line> |

package/skills/gsd-path-inspect/templates/state.md

@@ -0,0 +1,27 @@
+---
+pipeline: gsd-path/v2
+project: <slug>
+milestone: null     # set by define; names the archive directory at ship
+phase: define       # v2 tokens: inspect | define | research | decide | roadmap | plan | build | ship | shipped
+                    # inspect only for brownfield; greenfield starts at define
+                    # roadmap only in program flow (CHARTER.md exists)
+status: active      # active | done | blocked; shipped is only phase: shipped + status: done
+branch: null        # bound per milestone as gsd-path/M00N; after integration
+                    # the router rebinds before any next-milestone file change
+                    # the bound branch is never main; ship integrates it there
+archive: null       # persisted archive transaction path; never recomputed
+integration_default: direct # direct | pull-request; project setting
+integration: direct # current milestone; may override the default before build
+integration_source: default # default | milestone; preserves override provenance
+---
+
+# Project State
+
+One file, always current. The router reads this first; every phase updates
+it on completion. If this file and the artifacts disagree, the artifacts win
+— fix this file.
+
+## Log
+
+<!-- append one line per transition: date, phase, event -->
+- YYYY-MM-DD — <phase> — project initialized

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

@@ -0,0 +1,98 @@
+---
+name: gsd-path-loop
+description: Use only when the user explicitly invokes $gsd-path-loop. Runs one bounded loop pass from a LOOP.md spec — gate checks, independent verification, one fix worker, telemetry. Autonomy lives in the external scheduler that invokes this skill; the skill never schedules itself.
+---
+
+# GSD Path Loop
+
+One invocation = one bounded pass. The bundled deterministic helper
+[loop_run.py](scripts/loop_run.py) owns the gates — atomic claim, verify,
+finish, status — and its output is the only gate authority; do not
+reimplement that logic in model reasoning. The model owns what the helper
+cannot: reading the spec's prose, dispatching one fix worker, and feeding
+failures back. Fill new specs from the canonical
+[LOOP.md template](templates/loop.md); a filled dogfood example lives at
+[examples/ci-repair.LOOP.md](examples/ci-repair.LOOP.md).
+
+Run every helper command from the repository root — relative paths in the
+spec (`log:`, `skip_when:`, `verify:`) resolve against the working
+directory. Use the bundled copy of the helper next to this file. When the
+repository has a `.project/`, first run the bundled
+`scripts/discussion_records.py pending --repo <absolute-root>`; when
+`.project/discuss/ANSWERS.md` is absent, continue. A pending follow-up owned
+by loop work blocks the pass with links to ANSWERS.md.
+
+This skill never advances a gsd-path phase gate: it wraps bounded work, it
+does not route the pipeline.
+
+## Process
+
+1. **Read the spec.** Read the whole LOOP.md: machine fields and prose
+   sections (Goal, Worker scope, Feedback route, Human gates, Stops, Output).
+   The prose binds the worker brief below.
+2. **Claim.** Before verify or worker dispatch, run `python3
+   scripts/loop_run.py claim --spec <path>`. The atomic result is the only
+   admission decision. On `run`, retain the returned `claim` and admitted
+   limits for this pass. On `skip` with `recovery.recoverable: false`, another
+   pass still owns its admitted lease: report that the loop is already active
+   and stop without finishing or dispatching work. On another `skip` without
+   an expired claim, report the reason and stop; no outcome exists to finish.
+   Only when the helper returns `recovery.recoverable: true` and the expired
+   `claim`, close that exact prior claim as recovery before stopping:
+   `python3 scripts/loop_run.py recover --spec <path> --claim <returned
+   claim>`. The helper derives the elapsed time, completed verify cycles, and
+   truthful result from the latest verify (`pass`, `fail`, or `blocked` when
+   none completed). Never start work under a prior claim.
+3. **Baseline verify.** Run `python3 scripts/loop_run.py verify --spec
+   <path> --claim <retained claim>`. The helper enforces the claim's one
+   admitted wall-clock deadline across every verify command and every later
+   verify invocation. On `pass`, the goal is already green: record `pass` with
+   `finish` for the retained claim and `--iterations 0`, report, and stop. A
+   green baseline never dispatches a worker.
+4. **One bounded worker.** On `fail`, dispatch ONE fix worker (v1: single
+   worker, no fan-out) with the exact failing commands and output tails from
+   the helper, plus the spec's Worker scope. The worker fixes the smallest
+   failed unit named by the Feedback route — not the whole goal.
+5. **Independent verify.** The wrapper re-runs `verify` with the same
+   `--claim`; worker claims are
+   not evidence. On `fail`, feed the new failing output back to the worker.
+   The helper appends each verify result and refuses a verify beyond
+   `max_iterations` fix → verify cycles. Stop when that limit or the admitted
+   `wall_clock` is spent, whichever comes first.
+6. **Blocked.** When the worker cannot proceed, or the only remaining fix
+   needs a Human gates action, stop with `BLOCKED: <reason>` naming the
+   gate — never perform the gated action to unblock.
+7. **Finish.** Every admitted pass has exactly one terminal outcome. Append it
+   with `python3 scripts/loop_run.py finish --spec <path> --claim <retained
+   claim> --result pass|fail|blocked|skipped --iterations <n>
+   [--notes ...] [--rescue]`. The helper checks `<n>` against its verify events
+   and derives elapsed time from the claim. Use the exact same claim for
+   baseline pass, successful repair, exhausted verification, human-gate
+   block, or another terminal stop. Rerunning the identical `finish` is the
+   only completion retry.
+8. **Report.** Close per the AGENTS.md asking conventions: **Outcome** —
+   what changed, or why nothing ran; **Review** — a Markdown link to the
+   spec's log path (or the spec itself when no record was written), resolved
+   absolute path printed if the host cannot render links; **Next** — the one
+   question or action now required. `python3 scripts/loop_run.py status
+   --spec <path>` gives the aggregate counters when the user asks how the
+   loop is trending; `acceptance_rate` divides accepted by accepted plus
+   rejected — blocked and skipped runs are not evaluations.
+   `wall_clock_per_accept_seconds` divides total all-run wall clock by
+   accepts, so blocked and rejected runs raise it.
+
+## Rules
+
+- Never commit, push, tag, or mutate git state — a loop pass leaves version
+  control to the user.
+- Never edit tests to match broken code. If the test is the bug, say so in
+  the report and stop; weakening a verifier is a human-gate action.
+- Never touch paths the spec's Worker scope declares read-only.
+- Verify output tails are persisted to the spec's log; a verify command must
+  never echo secrets or credentials.
+- Human gates are never-auto: reaching one means `BLOCKED: <reason>`, not a
+  judgment call.
+- The helper's atomic `claim` output decides whether a pass runs. `check` is
+  preview-only and never authorizes verify, worker dispatch, or mutation.
+- A pass that cannot honestly reach green stops per the spec's Stops and
+  records the truth; silent partial success is the worst outcome.

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

@@ -0,0 +1,6 @@
+interface:
+  display_name: "GSD Path Loop"
+  short_description: "Run one bounded loop pass from a LOOP.md spec"
+  default_prompt: "Use $gsd-path-loop to run one bounded loop pass from a LOOP.md spec."
+policy:
+  allow_implicit_invocation: false

package/skills/gsd-path-loop/examples/ci-repair.LOOP.md

@@ -0,0 +1,61 @@
+# LOOP — ci-repair
+
+<!-- Dogfood spec for the gsd-path distribution repo itself. One pass repairs
+     a failing CI trio: pytest, the node installer tests, and the resource
+     sync check. Invoke from the repository root. -->
+
+loop: ci-repair
+status: active
+trigger: manual
+cooldown: 10m
+verify: python3 -m pytest tests/ -q
+verify: npm test
+verify: python3 scripts/sync_skill_resources.py --check
+max_iterations: 3
+wall_clock: 30m
+period: 24h
+period_budget: 4h
+log: .project/loop/ci-repair.LOG.jsonl
+
+## Goal
+
+The three verifier commands above all exit 0 — the same trio
+`.github/workflows/ci.yml` runs. Anything less is a failure, not a partial
+success.
+
+## Worker scope
+
+One fix worker repairs the failing test, installer check, or sync drift at
+its root cause. The worker must never: commit, push, or tag; edit a test to
+match broken product code; edit generated per-skill copies under
+`skills/gsd-path-*/{references,templates,scripts}/` instead of their
+canonical sources (`skills/gsd-path/` and `scripts/`); or touch files outside
+the failing unit's blast radius.
+
+## Feedback route
+
+On a failed verify, the worker gets the exact failing command and its output
+tail from `loop_run.py verify`, aimed at the smallest failed unit — the one
+failing test file, installer assertion, or sync mismatch — not the whole
+suite.
+
+## Human gates
+
+- Any commit, push, or tag.
+- Weakening, deleting, or skipping a test or verifier to reach green.
+- Editing a canonical template/reference and its generated copies in
+  conflicting directions (sync's wrong-direction-edit warning).
+- Changing CI itself (`.github/workflows/ci.yml`).
+
+## Stops
+
+- `pass` — all three verify commands exit 0.
+- `fail` — max_iterations or the 30m wall_clock budget is spent.
+- `blocked` — the only remaining fix needs a human-gate action; report
+  `BLOCKED: <reason>` and stop.
+
+## Output
+
+Append-only claim, verify, and finish records in
+`.project/loop/ci-repair.LOG.jsonl`, then the Outcome / Review / Next report
+naming the verify result, helper-counted iterations, and the log path.

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