@opengsd/gsd-path 1.0.0

package/skills/gsd-path-define/templates/charter.md

@@ -0,0 +1,50 @@
+# Charter — <program name>
+
+<!-- Written by $gsd-path-define program mode. Enduring program intent:
+     vetoes and constraints here override every milestone. Amended only by an
+     explicit user ruling recorded under Corrections. Lives at .project/
+     top level and persists across milestones; it never archives. -->
+
+Review panel: off   <!-- off | detected | claude,gpt,grok,composer,gemini,
+                      deepseek,kimi,qwen — durable
+                      program default for optional cross-model plan and
+                      wave review. Milestone INTENT copies this value and
+                      may override it. off is the default. Named values
+                      name at most 3 families. -->
+
+## Vision
+
+<2–4 sentences: the program's end state and why it matters.>
+
+## Full scope: in
+
+<!-- Everything the program will deliver, grouped by capability area. The
+     roadmap slices this list; every item must map to at least one milestone. -->
+- <capability area>: <what it includes>
+
+## Full scope: out (vetoes)
+
+<!-- Hard limits. No milestone, research dispatch, plan, or task may include
+     these. -->
+- <vetoed item> — <user's stated reason, verbatim where possible>
+
+## Constraints
+
+<Program-level stack, budget, deadline, integrations, compliance.>
+
+## Program success criteria
+
+<!-- Observable statements checked when the last milestone ships. -->
+1. <criterion — a thing you can run/measure/see>
+
+## Open questions
+
+<!-- Unresolved at program define end. Tags: RESEARCH (program research
+     answers it), NEEDS-USER (a human decision, surface at next checkpoint). -->
+- [RESEARCH] <question>
+- [NEEDS-USER] <question>
+
+## Corrections
+
+<!-- Verbatim user rulings that amend this charter. Append-only. -->
+- <date>: "<what the user said>"

package/skills/gsd-path-define/templates/intent.md

@@ -0,0 +1,98 @@
+# Intent — <project name>
+
+<!-- Written by $gsd-path-define. Every downstream agent reads this first.
+     Constraints and vetoes here override everything downstream. -->
+
+Lane: standard   <!-- standard | quick | milestone — quick: at most two
+                      deliverable-sized tasks in one wave, no RESEARCH or
+                      NEEDS-USER items, no cross-wave risk; set by define at
+                      approval. Quick skips research and decide. Milestone:
+                      derived from an approved ROADMAP.md entry in a program;
+                      research/decide run only when the entry has open
+                      questions. -->
+
+Review panel: off   <!-- off | detected | claude,gpt,grok,composer,gemini,deepseek,kimi,qwen — this
+                      milestone's panel setting. In program flow, copy
+                      CHARTER.md's durable default and override only when
+                      the user says so. off is the default. detected uses
+                      advertised host families except the parent, at most 3.
+                      Named families are an assertion, at most 3. Quick
+                      lane stays off. -->
+
+Finding skeptics: off   <!-- off | on — build spawns one read-only skeptic
+                      per blocking deep-review finding before fix tasks
+                      are opened; a refuted finding spawns no fix task unless
+                      the user explicitly overrides all cycle refutations.
+                      off is the default. Quick lane stays off. -->
+
+Surfaces: none   <!-- none | comma-separated list of the human-facing
+                      surfaces this milestone delivers: a web app, a CLI, an
+                      HTTP API. Anything a person opens, sees, or types into
+                      is a surface. Use none only when nobody touches this
+                      work directly — a library, a migration, internals.
+                      Every named surface needs a success criterion
+                      observable there and a PLAN.md Surface contract. -->
+
+## Summary
+
+<3–5 sentences: the problem, who has it, what the first release does. This is the
+paragraph the user signed off on — do not edit without a new sign-off.>
+
+## Problem
+
+<What hurts today, for whom, how badly. Evidence if the user gave any.>
+
+## Users
+
+<Who, how many, how technical, what they use today.>
+
+## Success criteria
+
+<!-- Observable statements, numbered from 1. PLAN.md maps each to a task
+     AC and Verify as SC1, SC2, …. Wave review checks the SCs a wave owns.
+     Final review checks every SC.
+     Every surface named above needs at least one criterion a person can
+     observe at that surface — a screen reached, an output seen — never a
+     passing test standing in for the experience. -->
+1. <criterion — a thing you can run/measure/see>
+2. ...
+
+## Scope: in
+
+<The smallest version that hits the success criteria. Bullet list.>
+
+## Scope: out (vetoes)
+
+<!-- Hard constraints. Nothing in research, plans, or tasks may include these. -->
+- <vetoed item> — <user's stated reason, verbatim where possible>
+
+## Constraints
+
+<Stack preferences, deadline, budget, existing code, integrations, compliance.>
+
+## Current state (brownfield only)
+
+<!-- Filled from evidence-codebase.md during brownfield define. Omit the
+     section entirely for greenfield projects. -->
+- **What exists**: <stack, architecture, maturity in 2–3 sentences>
+- **Must not break**: <existing behavior the user ruled protected — these are vetoes>
+- **Doc-vs-code rulings**: <each DOCS-AUDIT conflict → user's ruling: fix-doc | fix-code | accept-drift>
+- **Ground truth**: `<track>/research/evidence-codebase.md`, `<track>/research/DOCS-AUDIT.md`
+
+## Risks
+
+<!-- What the user is most unsure about. Research prioritizes these. -->
+- <risk>
+
+## Open questions
+
+<!-- Unresolved at define end. Tags: RESEARCH (research phase answers it),
+     NEEDS-USER (a human decision, surface at next checkpoint). -->
+- [RESEARCH] <question>
+- [NEEDS-USER] <question>
+
+## Corrections
+
+<!-- Verbatim user corrections from playback and later phases. Append-only.
+     These are the highest-signal intent data in the file. -->
+- <date>: "<what the user said>"

package/skills/gsd-path-define/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-discuss/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: gsd-path-discuss
+description: Hold an explicit, evidence-grounded discussion about an active GSD Path milestone from any phase, preserve the verbatim dialogue and answer records under .project/discuss/, use local code and existing artifacts before focused research, challenge unsupported assumptions, and identify the phase owner for follow-up. Use only when the user explicitly invokes $gsd-path-discuss to ask questions, explore a decision, request a progress explanation, or close a discussion without advancing the pipeline.
+---
+
+# GSD Path Discussion
+
+Use this skill as an interruptible sidecar to the active GSD Path pipeline. Keep
+the conversation in the main user thread, ground claims in the repository and
+the current phase artifacts, and save the exchange before returning the answer.
+
+Routing instructions are caller handoffs under the AGENTS.md handoff rule;
+tell the user which phase owns the follow-up and never invoke it yourself.
+
+## Preconditions and ownership
+
+1. Resolve the project root from the working directory. Read `AGENTS.md`,
+   `WORKFLOW.md`, and `.project/STATE.md` before answering.
+2. Require a real `.project/STATE.md` whose frontmatter contains
+   `pipeline: gsd-path/v2`. If it is missing, foreign, malformed, or a
+   symlink, stop and tell the user to invoke `$gsd-path` for ownership recovery.
+   Do not create state merely to hold a discussion.
+3. Accept any active milestone phase except `shipped`: inspect,
+   define, research, decide, roadmap, plan, build, or ship. Use the
+   state status currently recorded on disk. A shipped milestone is archived and must not be
+   reopened by this sidecar; start a new milestone first.
+4. Resolve the bundled `scripts/discussion_records.py`,
+   [dialogue template](templates/dialogue.md), and
+   [answers template](templates/answers.md) to absolute paths. Run its `prepare`
+   command with the absolute repository and template paths before reading any
+   records. This deterministic helper validates STATE ownership, locks STATE,
+   recovers interrupted paired appends, restores an uncommitted review archive
+   without editing it, creates the exact record pair when absent, and fails on
+   stale or malformed state. Do not reproduce those operations manually.
+5. Read only the helper-returned absolute DIALOGUE.md and ANSWERS.md paths.
+6. Do not change `STATE.md`, phase status, `INTENT.md`, `SYNTHESIS.md`,
+   `PLAN.md`, task frontmatter, review verdicts, or archive
+   contents. Discussion can propose a change and name its owner; the owning
+   phase must apply it through its normal gate.
+
+The helper serializes writers and rechecks STATE immediately before a paired
+publication. Never commit the records: the current phase orchestrator is their
+checkpoint owner and includes them as append-only bookkeeping in its next
+normal `.project/` checkpoint. The answer's named next owner separately owns
+the target artifact and disposition receipt.
+
+## Grounding and pushback
+
+Use the authority order from `AGENTS.md`:
+
+- Treat the user's current words as the question, but treat intent vetoes and
+  recorded corrections as hard constraints.
+- Treat settled synthesis decisions and the current plan/task contract as
+  governing phase inputs. Surface a conflict; never average sources or quietly
+  override a gate.
+- Inspect the relevant implementation, callers, tests, and phase artifacts.
+  Use search to locate evidence, then read the code or run an allowed,
+  meaningful check before claiming behavior. Cite exact repository paths and
+  line numbers when practical. Never describe an unrun command as passing.
+- Separate observed fact, inference, recommendation, and user decision. If the
+  premise is weak, push back plainly with the evidence and explain the smallest
+  safer alternative.
+
+Read only the phase-specific inputs needed for the question:
+
+| Phase | Start with |
+| --- | --- |
+| inspect | codebase map and docs audit |
+| define | intent and inspection evidence |
+| research | intent, research manifest, and relevant evidence |
+| decide | intent, evidence, and synthesis |
+| roadmap | charter, program synthesis, and the roadmap |
+| `plan` | intent, synthesis, plan, and affected task contracts |
+| `build` | intent, synthesis, plan, task frontmatter/logs, wave reviews, and STATE log |
+| ship | intent, plan, task frontmatter, STATE log, and relevant review artifacts |
+
+Then inspect the code that can prove or disprove the claim. Do not reread the
+whole repository when a focused path set answers the question.
+
+## Focused research
+
+Use existing `.project/research/` evidence first. If the question depends on a
+current external fact, an unfamiliar library behavior, or an unresolved intent
+risk, perform focused research during the discussion when the required search
+or source-reading capability is available. Record the query/scope, checked
+sources, and confidence in the answer record.
+
+Do not launch the full `$gsd-path-research` phase from this sidecar. That phase
+owns a legal state transition and a gated `RESEARCH.md` handoff; invoking it
+from an arbitrary phase would bypass the pipeline contract. If the result must
+become formal milestone evidence, record a `[RESEARCH]` follow-up and name
+`gsd-path-research` as the next owner. If research is unavailable, mark the
+answer `NEEDS-USER` or `unverifiable` instead of filling the gap from memory.
+
+## Discussion loop
+
+For each invocation:
+
+1. Identify the current phase/status and discussion thread. Run the helper's
+   `threads` command to list existing thread ids, topics, and statuses; do not
+   parse DIALOGUE.md for them. Reuse a stable thread id
+   (`T###`) when the user is continuing a topic; request `new` for a
+   distinct topic and let the helper allocate its id. Classify the
+   request as a fact check, diagnosis, decision, challenge, progress question,
+   or follow-up request.
+2. Gather the smallest sufficient local evidence, then focused research only
+   when needed. Record conflicts and uncertainty before forming a conclusion.
+3. Answer in the main conversation. State the conclusion first, then the
+   reasoning, evidence, pushback or alternatives, confidence, and the phase
+   owner for any action. When a formal follow-up is required, tell the user to
+   invoke `$gsd-path`; the router will route the pending answer to that owner.
+   Do not leave the user with only an owner name or direct phase command. Ask
+   only the next question required to resolve the user's decision; use the
+   host's interactive input facility when available.
+4. Before returning, provide the semantic turn fields to the helper's `append`
+   command as one JSON object via `--input`, passing the same absolute template
+   paths as `prepare`. The object requires these non-empty fields:
+   `topic`, `user`, `assistant`,
+   `question`, `status`, `thread_status`, `conclusion`, `reasoning`,
+   `evidence`, `research`, `confidence`, `unresolved`, `next_owner`,
+   `target_artifact`, and `follow_up`. `thread` is optional: pass an existing
+   `T###` id to continue a thread, or omit it (or pass `new`) to let the
+   helper allocate the next thread id. An optional `date` field overrides the
+   record date (`YYYY-MM-DD`). Every listed field except `user` and
+   `assistant` must be a single line; the helper rejects an incomplete payload
+   and names every missing or multi-line field in one error. The helper allocates D/A ids,
+   reply and supersession links, records the current phase/status, and publishes
+   DIALOGUE.md and ANSWERS.md as a recoverable pair. Preserve the user's message
+   and returned assistant answer verbatim in `user` and `assistant`.
+5. Use `working` only when the answer is explicitly
+   provisional or asks another question, `NEEDS-USER` when a human choice or
+   missing evidence blocks it, and `final` when it resolves the bounded question
+   or the user accepts/closes the thread. Set `Follow-up: required` only when a
+   named phase must update the named target artifact; otherwise use `none`. A
+   final answer record is durable context, not approval to advance a phase.
+
+If the user corrects a fact, sets a veto, or makes a decision, preserve the
+words verbatim in both the dialogue and answer records and identify which
+formal artifact the owning phase must update. Such a record uses `Follow-up:
+required`; it remains pending until the owner appends a fixed-format
+`Disposition X###` receipt. The discussion sidecar never writes its own
+disposition. After a helper failure, do not claim the dialogue or answer was
+saved; the next `prepare` recovers an interrupted paired publication before
+accepting another turn.
+
+## Output contract
+
+Every completed turn leaves these project-local artifacts:
+
+- `.project/discuss/DIALOGUE.md` — append-only transcript of the exchange.
+- `.project/discuss/ANSWERS.md` — append-only answer and decision records,
+  with final answers clearly marked `final`.
+
+Keep answer records concise but self-contained: question, phase/status,
+conclusion, reasoning or pushback, evidence/citations, research used or why it
+was not needed, confidence, unresolved tags, next owner, target artifact, and
+follow-up state. Do not duplicate a formal phase handoff or silently edit one
+on the user's behalf. End the user response with **Outcome**, Markdown
+**Review** links to the resolved absolute DIALOGUE.md and ANSWERS.md paths. For
+a required follow-up, **Next** names the pending owner and tells the user to
+invoke `$gsd-path`; otherwise it gives the next discussion question or says
+that no action is required.

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

@@ -0,0 +1,6 @@
+interface:
+  display_name: "GSD Path Discussion"
+  short_description: "Discuss any phase with durable answers"
+  default_prompt: "Use $gsd-path-discuss to reason through this GSD Path question and save the dialogue and final answer."
+policy:
+  allow_implicit_invocation: false

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