@opengsd/gsd-path 1.0.0

package/skills/gsd-path-docs-audit/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-forensics/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: gsd-path-forensics
+description: Use only when the user explicitly invokes $gsd-path-forensics. Read-only diagnosis of a stuck GSD Path pipeline. Runs existing helpers and names the exact retry command; never mutates state, git, or artifacts.
+---
+
+# GSD Path Forensics
+
+One invocation = one read-only diagnosis. The bundled
+[pipeline_diagnose.py](scripts/pipeline_diagnose.py) owns the probes; do not
+re-derive stuckness from a directory listing or `git status` prose.
+
+This skill never advances a phase gate, never edits `.project/`, and never
+runs git mutations.
+
+When the project's `.gsd-path/runtime/` exists, resolve bundled helper paths
+for `pipeline_state.py`, `pipeline_git.py`, `archive_milestone.py`,
+`promote_lookahead.py`, `discussion_records.py`, and `pipeline_diagnose.py`
+to that runtime. It is the guard-approved location on a closed milestone.
+Use the skill bundle only when no project-local runtime exists.
+
+## Process
+
+1. **Diagnose.** Run `python3 <absolute-bundled-pipeline_diagnose.py> diagnose
+   --repo <absolute-root>`. Treat the JSON as the only diagnosis.
+2. **Report.** Present **Outcome** as `status` (`ok`, `stuck`, or `unowned`)
+   plus every `stuck` finding's `evidence`. **Review** links STATE.md when
+   `status_snapshot.path` exists; otherwise link the repo root. **Next** is the
+   `retry` string from the first `stuck` finding, or `$gsd-path status` when
+   the verdict is `ok`.
+3. **Stop.** Do not invoke the named retry. Do not apply undo. Name
+   `$gsd-path-undo` only when a finding `id` is `undo-available` and the user
+   asked to roll work back.
+
+## Rules
+
+- Never write a forensics file under `.project/`. The helper JSON is the
+  artifact.
+- Never resume a journal, bind a branch, or reset HEAD from this skill.
+- Same-model agreement is not evidence: the helper output is the evidence.

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

@@ -0,0 +1,6 @@
+interface:
+  display_name: "GSD Path Forensics"
+  short_description: "Read-only diagnosis of a stuck GSD Path pipeline"
+  default_prompt: "Use $gsd-path-forensics to diagnose a stuck GSD Path pipeline."
+policy:
+  allow_implicit_invocation: false

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