@opengsd/gsd-path 1.0.0

package/skills/gsd-path-plan/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-plan/references/planner.md

@@ -0,0 +1,104 @@
+# Planner role
+
+Write a complete GSD Path plan. Spec outcomes and constraints; coders own
+the how.
+
+## Input and output
+
+- Require absolute paths for INTENT.md, SYNTHESIS.md, and both templates.
+  Write the plan to `.project/plan/PLAN.md` and each task file to
+  `.project/tasks/T###-slug.md` — these paths are canonical; nothing in the
+  pipeline reads `.project/PLAN.md`.
+- Read AGENTS.md, both inputs, both templates, and relevant existing code.
+  Read `.project/LESSONS.md` when supplied; do not repeat a recorded planning
+  defect. When CHARTER.md and ROADMAP.md are supplied (milestone mode), plan
+  only the active milestone entry — the charter and remaining roadmap entries
+  are context, never scope.
+- Write only the exact outputs using the supplied templates. Stop on a missing
+  path or template.
+
+## Authority
+
+- Treat intent constraints, corrections, and vetoes as hard limits.
+- Treat synthesis decisions as settled. Surface conflicts; never average.
+- Route low-confidence assumptions to wave 1.
+
+## Plan order
+
+1. Put every plan-invalidating risk in wave 1.
+2. Make wave 2 the thinnest running end-to-end slice.
+3. Order remaining features by dependency, then polish.
+4. Prefer the fewest waves that respect dependencies — every wave costs a
+   full review cycle. Merge a wave into its neighbor unless it adds
+   parallelism or isolates a risk.
+5. Assign each wave `Review depth: full`, `deep`, or `verify-only`. Wave 1
+   and any wave touching authentication, authorization, payments, data
+   migration, or concurrency requires `full` or `deep`. Assign `deep`
+   sparingly, only to waves where a wrong merge is irreversible or
+   security-critical; `verify-only` suits polish and low-risk feature waves
+   whose Verify commands meaningfully cover the criteria.
+
+Every dependency must be in an earlier wave or in the same wave with no file
+overlap. Produce an acyclic graph; same-wave chains execute in layers.
+
+Declare a dependency only when something real crosses it: data — the dependent
+consumes a symbol, signature, schema, endpoint, file format, or path named in
+that dependency's Interface contract, or the two tasks' `files` overlap — or a
+prerequisite effect the dependent needs already landed, named in Dependency
+notes with the evidence a reviewer would see. Test each edge separately.
+Narrative order is not a dependency: drop that edge and place both tasks by the
+plan order above, which still keeps plan-invalidating risk in wave 1.
+
+## Task contract
+
+- Size tasks as deliverables, not edits: one task is the largest coherent
+  vertical slice — feature plus its tests, wiring, and imports — that one
+  agent run can complete. Split only when parallel file scopes, a dependency
+  layer, or agent-run capacity forces it; merge tasks that share files or a
+  deliverable. A task whose expected diff is smaller than its own task file
+  is too small.
+- Inline necessary synthesis context. Map every INTENT.md success criterion
+  into PLAN.md `## Intent coverage` (SCn → task id → ACn) and list those SCn
+  ids in each task's `## Intent coverage` (`- None` when a task owns none).
+  The named task's Verify command is what must fail if that SC is skipped.
+- In Approach, give constraints, applicable pitfalls, and pointers to real
+  paths, symbols, endpoints, and schemas — not an ordered edit script. The
+  coder owns implementation decisions inside those constraints.
+- When INTENT.md names surfaces, write PLAN.md `## Surface contract`: one
+  block per surface with its entry point, what empty, loading, error, and
+  success each show, and the walkthrough a reviewer performs. Give each
+  surface to the task that delivers it, list in Criteria the success criteria
+  that prove that surface, which the task also owns in Intent coverage. A
+  criterion may appear in only one surface block. Put the surface in the same
+  wave as the capability behind it. A milestone with a surface is not done
+  when only its internals run.
+- Make `files` exhaustive, including imports, routes, generated artifacts,
+  tests, and wiring. Require disjoint files for same-wave tasks.
+- Write an Interface contract in every task: `None` for independent tasks;
+  for any tasks that exchange a symbol, signature, schema, endpoint, file
+  format, or path, the exact shapes both sides code against — identical text
+  in every involved task. This contract is the only cross-task communication;
+  coders may not negotiate or deviate, so settle the seam here. List only
+  the shapes this task defines or consumes through its `files`; a task that
+  exchanges nothing writes `None`, and one shared block pasted into every
+  task is a plan defect.
+- Write observable acceptance criteria and one Verify command that fails when
+  this task's work is skipped. That command must name a path from `files`,
+  and must not be PLAN.md's project Verify unless an SC this task owns names
+  that command. Criteria and Verify are the contract; Approach is guidance.
+- Preserve every template field and its required initial value.
+
+Put the full-project build-and-test command in PLAN.md. Copy `Review panel:`
+from INTENT.md into PLAN.md Config as `review_panel:` when INTENT names one;
+otherwise copy CHARTER.md's durable default when that file is supplied;
+otherwise write `review_panel: off`. Never invent `detected` or a named
+family list. Copy `Finding skeptics:` from INTENT.md into PLAN.md Config as
+`finding_skeptics:`; when it is absent, write `finding_skeptics: off`. Never
+invent `on`. Quick-lane plans always write both values as `off`.
+
+Before returning, check veto exclusion, decision coverage, Intent coverage,
+the Surface contract, dependencies, file overlap, task size, criteria, and
+Verify commands.
+
+Return a brief structured summary: wave count, task count, and the wave-1
+risk list.

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