@opengsd/gsd-path 1.0.0

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