@opengsd/gsd-path 1.0.0

package/skills/gsd-path-build/scripts/token_budget.py

@@ -0,0 +1,146 @@
+#!/usr/bin/env python3
+"""Persist observed Codex output usage and block admission after exhaustion.
+
+This is an admission gate, not an in-flight generation cap. Codex CLI does not
+expose a hard output-token cap. Unobserved calls are not budget evidence.
+"""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+try:
+    from _common import atomic_write
+    from loop_run import log_lock
+except ModuleNotFoundError:  # pragma: no cover - package imports
+    from scripts._common import atomic_write
+    from scripts.loop_run import log_lock
+
+
+SCHEMA = "gsd-path/token-budget/v1"
+
+
+def positive(value):
+    result = int(value)
+    if result <= 0:
+        raise argparse.ArgumentTypeError("budget must be positive")
+    return result
+
+
+def output_usage(path: Path) -> int:
+    usages = []
+    child_usage = None
+    child = False
+    starts = 0
+    complete = False
+    text = path.read_text(encoding="utf-8")
+    try:
+        document = json.loads(text)
+    except ValueError:
+        document = None
+    if isinstance(document, dict) and isinstance(document.get("usage"), dict):
+        # Claude Code `-p --output-format json`: one document with the run's usage.
+        usages.append(document["usage"].get("output_tokens"))
+        text = ""
+    for line in text.splitlines():
+        event = json.loads(line)
+        if "raw" in event:
+            event = json.loads(event["raw"])
+        if event.get("type") == "turn.completed":
+            usages.append(event["usage"]["output_tokens"])
+        payload = event.get("payload", {})
+        if event.get("type") == "session_meta":
+            source = payload.get("source", {})
+            child = isinstance(source, dict) and "subagent" in source
+        if event.get("type") == "event_msg":
+            if payload.get("type") == "task_started":
+                starts += 1
+                complete = False
+            elif payload.get("type") == "token_count" and payload.get("info"):
+                child_usage = payload["info"]["total_token_usage"]["output_tokens"]
+            elif payload.get("type") == "task_complete":
+                complete = True
+    if not usages and child and starts == 1 and complete and child_usage is not None:
+        # Only a single native invocation has an unambiguous cumulative counter.
+        usages = [child_usage]
+    if not usages or any(type(value) is not int or value < 0 for value in usages):
+        raise ValueError("complete supported output usage is unavailable; budget is unproven")
+    return sum(usages)
+
+
+def operate(args):
+    ledger = args.ledger.absolute()
+    if ledger.is_symlink():
+        raise ValueError("ledger must be a real file")
+    with log_lock({"log": str(ledger)}):
+        if args.action == "configure":
+            policy = {"schema": SCHEMA, "host": "codex-cli", "metric": "output_tokens",
+                      "task_limit": args.task_limit, "session_limit": args.session_limit,
+                      "authority": args.authority}
+            if ledger.exists():
+                data = json.loads(ledger.read_text())
+                if any(data.get(key) != value for key, value in policy.items()):
+                    raise ValueError("existing session policy differs; configuration cannot reset usage")
+            else:
+                data = {**policy, "observations": {}}
+                atomic_write(ledger, json.dumps(data, indent=2) + "\n")
+            return {"status": "configured", "hard_cap_supported": False}
+        data = json.loads(ledger.read_text())
+        if data.get("schema") != SCHEMA or data.get("host") != "codex-cli":
+            raise ValueError("unsupported budget ledger")
+        if args.action == "record":
+            source = str(args.events.resolve())
+            observation = {"task": args.task, "output_tokens": output_usage(args.events)}
+            previous = data["observations"].get(source)
+            if previous and (previous["task"] != args.task or
+                             previous["output_tokens"] > observation["output_tokens"]):
+                raise ValueError("observation cannot change task or reduce recorded usage")
+            data["observations"][source] = observation
+            atomic_write(ledger, json.dumps(data, indent=2) + "\n")
+            return {"status": "recorded", **observation, "hard_cap_supported": False}
+        observations = data["observations"].values()
+        task_used = sum(row["output_tokens"] for row in observations if row["task"] == args.task)
+        session_used = sum(row["output_tokens"] for row in observations)
+        task_remaining = max(0, data["task_limit"] - task_used)
+        session_remaining = max(0, data["session_limit"] - session_used)
+        reason = "observed usage is within budget; unobserved and in-flight usage is unproven"
+        blocked = not task_remaining or not session_remaining
+        if blocked:
+            reason = "observed output budget exhausted"
+        if args.require_hard_cap:
+            blocked = True
+            reason = "hard generation cap unsupported by Codex CLI"
+        return {"decision": "blocked" if blocked else "admit", "reason": reason,
+                "task_output_tokens": task_used, "session_output_tokens": session_used,
+                "task_remaining": task_remaining, "session_remaining": session_remaining,
+                "hard_cap_supported": False, "enforcement": "observed-admission-only"}
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description=__doc__)
+    subparsers = parser.add_subparsers(dest="action", required=True)
+    for name in ("configure", "record", "admit"):
+        command = subparsers.add_parser(name)
+        command.add_argument("--ledger", type=Path, required=True)
+        if name == "configure":
+            command.add_argument("--task-limit", type=positive, required=True)
+            command.add_argument("--session-limit", type=positive, required=True)
+            command.add_argument("--authority", required=True)
+        else:
+            command.add_argument("--task", required=True)
+        if name == "record":
+            command.add_argument("--events", type=Path, required=True)
+        if name == "admit":
+            command.add_argument("--require-hard-cap", action="store_true")
+    try:
+        result = operate(parser.parse_args(argv))
+    except (ValueError, OSError, KeyError, TypeError) as error:
+        print(json.dumps({"decision": "blocked", "reason": str(error)}))
+        return 1
+    print(json.dumps(result, sort_keys=True))
+    return 1 if result.get("decision") == "blocked" else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/gsd-path-build/scripts/workflow_run.py

@@ -0,0 +1,117 @@
+#!/usr/bin/env python3
+"""Run canonical workflow helpers with fixed arguments and fail-stop receipts."""
+
+import argparse
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+try:
+    from scripts import _common
+except ImportError:  # bundled copy inside a skill's scripts directory
+    import _common
+
+
+class StepFailed(RuntimeError):
+    pass
+
+
+def run_workflow(repo: Path, action: str, project_dir: str, expected_head: str = None,
+                 task_id: str = None, round_size: int = None) -> dict:
+    steps = []
+    scripts = Path(__file__).resolve().parent
+
+    def step(script, *arguments):
+        command = [sys.executable, "-B", str(scripts / script), *arguments]
+        completed = subprocess.run(command, cwd=repo, capture_output=True, text=True)
+        receipt = {"script": script, "command": command, "exit_code": completed.returncode,
+                   "stdout": completed.stdout, "stderr": completed.stderr}
+        steps.append(receipt)
+        if completed.stderr:
+            sys.stderr.write(completed.stderr)
+        if completed.returncode:
+            raise StepFailed(script)
+        try:
+            receipt["result"] = json.loads(completed.stdout)
+        except json.JSONDecodeError as error:
+            raise StepFailed(f"{script} did not return JSON") from error
+        return receipt["result"]
+
+    common = ["--repo", str(repo), "--project-dir", project_dir]
+    try:
+        if action == "route":
+            step("pipeline_state.py", "route", *common)
+        elif action == "lint-round":
+            head = subprocess.run(["git", "rev-parse", "--verify", "HEAD"],
+                                  cwd=repo, capture_output=True, text=True, check=True).stdout.strip()
+            step("check_task_briefs.py", "--repo", str(repo), "--base", head,
+                 "--tasks-dir", f"{project_dir}/tasks")
+            step("check_handoffs.py", "plan", *common)
+        elif action == "prepare-task":
+            task = step("isolation.py", "isolate-task", "--repo", str(repo),
+                        "--base", expected_head, "--task-id", task_id,
+                        "--round-size", str(round_size))
+            if task["mode"] == "serial":
+                step("isolation.py", "isolate-verify", "--repo", str(repo),
+                     "--base", expected_head, "--name", f"task-{task_id.lower()}-verify")
+        elif action == "build-evidence":
+            proof = step("build_state.py", "verify-landed", *common, "--head", expected_head)
+            # The landing proof has one canonical home; lean final-review reuse allows only this path.
+            evidence = repo / project_dir / "build" / "evidence.json"
+            _common.atomic_write(evidence, json.dumps(proof, indent=2, sort_keys=True) + "\n")
+            steps.append({"script": "workflow_run.py", "evidence": str(evidence)})
+        elif action == "prepare-final":
+            if project_dir != ".project":
+                raise StepFailed("final review requires the active milestone")
+            pending = step("discussion_records.py", "pending", "--repo", str(repo))
+            if pending["pending"]:
+                raise StepFailed("pending discussion requires its owner disposition")
+            step("build_state.py", "verify-landed", *common, "--head", expected_head)
+            step("lean_verification.py", "--repo", str(repo), "--expected-head", expected_head)
+        else:
+            pending = step("discussion_records.py", "pending", "--repo", str(repo))
+            if pending["pending"]:
+                raise StepFailed("pending discussion requires its owner disposition")
+            step("check_handoffs.py", "plan", *common)
+            head = subprocess.run(["git", "rev-parse", "--verify", "HEAD"],
+                                  cwd=repo, capture_output=True, text=True, check=True).stdout.strip()
+            step("check_task_briefs.py", "--repo", str(repo), "--base", head,
+                 "--tasks-dir", f"{project_dir}/tasks")
+            panel = ["validate-plan", "--plan", str(repo / project_dir / "plan/PLAN.md"),
+                     "--intent", str(repo / project_dir / "intent/INTENT.md")]
+            charter = repo / ".project/CHARTER.md"
+            if charter.exists():
+                panel += ["--charter", str(charter)]
+            step("review_panel.py", *panel)
+            if action == "approve-plan":
+                step("pipeline_state.py", "approve", *common, "--kind", "plan",
+                     "--expected-head", expected_head)
+    except (StepFailed, OSError, subprocess.CalledProcessError) as error:
+        return {"status": "blocked", "reason": str(error), "steps": steps,
+                "next": "$gsd-path-forensics"}
+    return {"status": "complete", "steps": steps}
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("action", choices=("route", "gate-plan", "approve-plan", "build-evidence", "lint-round", "prepare-task", "prepare-final"))
+    parser.add_argument("--repo", type=Path, required=True)
+    parser.add_argument("--project-dir", choices=(".project", ".project/next"), default=".project")
+    parser.add_argument("--expected-head")
+    parser.add_argument("--task-id")
+    parser.add_argument("--round-size", type=int)
+    arguments = parser.parse_args(argv)
+    if arguments.action in {"approve-plan", "build-evidence", "prepare-task", "prepare-final"} and not arguments.expected_head:
+        parser.error(f"{arguments.action} requires --expected-head")
+    if arguments.action == "prepare-task" and (not arguments.task_id or arguments.round_size is None):
+        parser.error("prepare-task requires --task-id and --round-size")
+    result = run_workflow(arguments.repo.resolve(), arguments.action,
+                          arguments.project_dir, arguments.expected_head,
+                          arguments.task_id, arguments.round_size)
+    print(json.dumps(result, sort_keys=True))
+    return 0 if result["status"] == "complete" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/gsd-path-build/templates/skeptic.md

@@ -0,0 +1,36 @@
+# Skeptic — wave <N>, cycle <C>
+
+<!-- Written by one finding-skeptic child. Advisory to fix-task batching
+     only: the inherit reviewer owns Wave verdict. -->
+
+- Criterion: <the failed criterion, verbatim from the lens file>
+- Criterion locator: <t001_ac2 | t001_files | sc3>
+- Lenses: <contract | adversarial | both>
+
+## Observations
+
+<!-- Repeat for every distinct lens observation. Collapse only true
+     duplicates. Give each observation a unique number and exactly one
+     verdict with that number below; unknown or duplicate verdict numbers
+     are invalid. The criterion locator, not these local numbers, is the
+     finding identity across cycles. -->
+
+### Observation <n> — <contract | adversarial>
+
+<the observation verbatim: criterion, observed result, file:line>
+
+## Observation verdicts
+
+### Observation <n>: <refuted | stands>
+
+<checked evidence for this observation>
+
+## Verdict
+
+<refuted | stands>
+
+## Evidence
+
+<checked evidence: the command re-run in the sidecar or the artifact
+re-read, with its result. A refuted verdict requires every observation above
+to be individually refuted; anything short of that is stands.>

package/skills/gsd-path-build/templates/task.md

@@ -0,0 +1,74 @@
+---
+id: T001
+title: <imperative, specific>
+wave: 1
+deps: []            # task ids whose output or landed effect this task needs
+status: pending     # orchestrator-owned: pending | in-progress | done | failed | blocked
+agent: null         # orchestrator-owned: set at dispatch
+base: null          # orchestrator-owned: clean layer SHA for isolated Verify
+worktree: null      # orchestrator-owned: isolated task worktree while active
+task_branch: null   # orchestrator-owned: gsd-path-task/<id> while parallel; null when serial
+files:              # every file this task may touch — dispatch checks overlap
+  - <path>
+---
+
+# T001 — <title>
+
+## Context
+
+<!-- 3–5 sentences. Everything the coder needs from SYNTHESIS, inlined.
+     The coder reads this file, INTENT.md, and the codebase. -->
+
+## Approach
+
+<!-- Constraints, applicable pitfalls from research, and pointers to real
+     paths, symbols, and schemas. Not an edit script — the coder owns the
+     how within these constraints and the acceptance criteria. -->
+- <constraint or pointer>
+
+## Interface contract
+
+<!-- Planner-owned. The exact shared symbols, signatures, types, paths,
+     schemas, or formats this task exchanges with other tasks. Required when
+     another task consumes this task's output or this task consumes a
+     sibling's; write the identical contract in every involved task. Otherwise
+     write `None`. Only shapes this task's `files` define or consume — never
+     the whole plan's contracts. Binding like the acceptance criteria: needing to deviate
+     is a plan defect — block, never negotiate or improvise. -->
+- None
+
+## Intent coverage
+
+<!-- SCn ids this task owns, matching PLAN.md Intent coverage. Write
+     `- None` when this task owns no INTENT success criterion. -->
+- SC1
+
+## Acceptance criteria
+
+<!-- Observable. The reviewer checks the diff against exactly these. -->
+1. <behavior/command/output that must be true>
+
+## Verify
+
+```bash
+<one command that fails if this task wasn't done; names a path from files>
+```
+<!-- Runs in a fresh sidecar worktree at the landed commit with nothing
+     installed. Provision dependencies inside the command when the project
+     needs them, e.g. `pnpm install --frozen-lockfile && pnpm vitest run
+     src/x.test.ts`. -->
+
+Heavy: no   <!-- yes when this command must not run beside another heavy Verify -->
+
+<!-- Fix tasks only: add ## Review findings before Log, with one
+     ### <canonical locator> block per group in the helper's batch.
+     Each block contains Criterion: <verbatim criterion> and all supplied
+     observations verbatim. Set deps to include the source tasks and files
+     to the batch's files. Ordinary tasks omit this section. -->
+
+## Log
+
+<!-- Append-only: coder summary, blocks (`NEEDS-ORCHESTRATOR: <question> —
+     readings: <candidates>` for contract ambiguity), orchestrator answers,
+     review verdicts, fixes. -->
+- <date> — created by planner

package/skills/gsd-path-build/templates/wave-panel.md

@@ -0,0 +1,25 @@
+# Panel — wave <N>, cycle <C>
+
+<!-- Written by one review-panel child. Advisory only: the inherit reviewer
+     owns Wave verdict. Kind criterion may be presented to the user when
+     Severity is high; preference stays a warning. -->
+
+- Family: <claude | gpt | grok | composer | gemini | deepseek | kimi | qwen>
+- Model: <exact advertised slug>
+- Depth: <full | adversarial>
+
+## Findings
+
+<!-- One ### F# block per finding, or a single `- none` line. -->
+
+### F1
+- Severity: high
+- Kind: criterion
+- Criterion: T001 acceptance 1
+- Evidence: src/app.py:12
+- Found: <what exists instead>
+- Fix direction: <concrete coder direction>
+
+## Summary
+
+<one paragraph; do not edit code, tasks, or the canonical wave review>

package/skills/gsd-path-build/templates/wave-review.md

@@ -0,0 +1,64 @@
+# Review — wave <N>, cycle <C>
+
+<!-- Written by the reviewer role in wave mode. File: wave-N.cycleC.md —
+     deep reviews use wave-N.cycleC.contract.md and
+     wave-N.cycleC.adversarial.md instead. Keep validated fields on their
+     own lines: Cycle holds only the number
+     (C > 1 means re-review after fixes; see previous cycle file). -->
+
+<!-- For quick single-full-wave final scope, include these two metadata lines
+     with actual values, otherwise omit them:
+Reviewed HEAD: <full review commit SHA>
+Review scope: final
+     In each surface SC block also include Surface, Check, and Observed fields
+     using the final-review format. Record the actual walkthrough evidence once. -->
+
+Wave verdict: <pass | blocked — blocked if any task fails>
+Cycle: <C>
+Depth: <full | deep | verify-only — verify-only is orchestrator-written from
+        its isolated Verify evidence; no independent reviewer ran>
+Lens: <contract | adversarial — deep reviews only; empty or omitted
+       otherwise>
+Tasks reviewed: <count>
+
+## T001 — <title>: <pass | fail>
+
+<!-- Per task criterion: copy the full acceptance/interface criterion verbatim
+     before the em dash; join wrapped lines with spaces. An AC id or summary
+     alone cannot be matched by review_findings.py. -->
+- ✅ <criterion> — <evidence: verify output / file:line checked>
+- ❌ <criterion> — found: <what exists instead, file:line>
+  fix: <concrete direction a coder can execute without re-investigating>
+
+Warnings (non-blocking):
+- <weakened test / unfailable verify / none>
+
+Contract violations (blocking):
+- ❌ <task changed path outside its files list> — <evidence and fix direction>
+
+<!-- Repeat per task. -->
+
+## Intent coverage
+
+<!-- One heading per INTENT.md success criterion owned by a task in this
+     wave, ending `: pass` or `: fail`. `scripts/check_handoffs.py wave
+     --review <this file>` gates the SC id set and verdicts. Omit this
+     section when no task in the wave owns an SC. -->
+
+### SC1 — <criterion>: <pass | fail>
+- ✅ <evidence: verify output / file:line checked>
+- ❌ <criterion> — found: <what exists instead, file:line>
+  fix: <concrete direction a coder can execute without re-investigating>
+
+## Fixed since last cycle
+
+<!-- C > 1 only: previously failed criteria now confirmed fixed (re-checked,
+     not assumed), and any regressions the fixes introduced. -->
+- <criterion> — confirmed fixed / regressed: <evidence>
+
+## Summary for orchestrator
+
+- blocked findings: <failed criteria grouped by disjoint file scope; the
+  orchestrator applies the configured skeptic or fix-task path>
+- repeat offenders: <criteria failing across cycles — possible plan defect>
+- warnings worth a human eye: <...or none>

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

@@ -0,0 +1,115 @@
+---
+name: gsd-path-decide
+description: Decide implementation direction from approved intent and complete research evidence, recording settled choices in SYNTHESIS.md. Use only when the user explicitly invokes $gsd-path-decide or an active $gsd-path router explicitly routes to this phase.
+---
+
+# GSD Path Decide Phase
+
+Dispatch one reasoning-intensive decider and validate its decision artifact.
+
+Routing instructions below are caller handoffs under the AGENTS.md handoff
+rule; never invoke an explicit-only sibling skill yourself.
+
+Before dispatch and again before completion, apply the AGENTS.md
+pending-answer rule with the bundled `scripts/discussion_records.py`; a
+follow-up owned by decide is resolved in SYNTHESIS.md, or the phase blocks.
+
+## Preconditions
+
+Require `pipeline_state.py validate --repo <absolute root> [--project-dir
+.project/next]` to pass; otherwise return to `$gsd-path` for ownership
+checking. Legal entry is `research/done` or `decide/active|blocked`. On
+`research/done`, enter with `pipeline_state.py transition`, expected
+phase/status `research/done`, exact branch and archive values, event `decision
+synthesis started`, and set phase/status `decide/active` (plus the same
+lookahead project dir); never edit STATE directly. `decide/done` or any later phase blocks rather
+than replacing decisions beneath an existing plan. When an active router
+supplies the lookahead track root `.project/next/`, evaluate these
+preconditions against the track instead; see Lookahead mode. Require
+`.project/intent/INTENT.md`, `.project/research/RESEARCH.md`, and every
+`evidence-*.md` file named as `dispatched` there. In program flow (CHARTER.md
+exists, no milestone INTENT yet) require `.project/CHARTER.md` in INTENT.md's
+place. A standard file may be absent
+only when the handoff manifest records that dimension as skipped; a missing or
+invalid manifest or dispatched file routes to `$gsd-path-research`. Include
+every additional `evidence-*.md` file present only when the manifest names it.
+
+Output path: when `.project/CHARTER.md` exists and `.project/ROADMAP.md` does
+not, this is program scope — the required output is `.project/SYNTHESIS.md`
+at the `.project/` top level; it persists across milestones and never
+archives. Otherwise the required output is `.project/research/SYNTHESIS.md`,
+which archives with its milestone.
+
+## Lookahead mode
+
+Entered only when an active router supplies the lookahead track root
+`.project/next/` while the active STATE.md is `build/active` in program
+flow. Evaluate every state and artifact precondition against the track:
+`.project/next/STATE.md` is the state file, and INTENT.md, RESEARCH.md, and
+the evidence files are read from `.project/next/`. The output is always
+milestone scope: `.project/next/research/SYNTHESIS.md` — the program
+SYNTHESIS.md already exists at the active `.project/` top level and is
+never rewritten here, so the program-scope output-path rule above does not
+apply. Run the research hand-off validator with `--project-dir
+.project/next`. Dispatch, gates, `NEEDS-USER` handling, and completion
+rules are unchanged; never write an active-path artifact.
+
+## Process
+
+1. Read the local [synthesis template](templates/synthesis.md),
+   `.project/research/RESEARCH.md`, and the bundled `scripts/check_handoffs.py`;
+   resolve each to an absolute path. Run the research hand-off validator before
+   dispatch so decide receives a complete, intentional evidence set.
+2. Read the local [decider role](references/decider.md), then follow
+   the local [runtime dispatch contract](references/dispatch.md) with
+   deterministic logical task name `decide`. Give it absolute paths to the role,
+   `AGENTS.md`, `WORKFLOW.md`, INTENT.md (or CHARTER.md in program flow),
+   RESEARCH.md, every evidence file, the
+   template, and the required output path from the Preconditions.
+3. Validate SYNTHESIS.md with `python3 <absolute check_handoffs.py> decide
+   --repo <absolute root> [--project-dir .project/next]`. Require one decision block for every genuinely open
+   choice in INTENT.md and the evidence, including stack and architecture
+   shape plus build-vs-buy when open. A choice already settled by an intent
+   constraint or the existing codebase belongs under `## Settled` as one line
+   citing the settling source — never a full block with an invented
+   runner-up. Require Decision, Runner-up, Evidence, and
+   Confidence in every decision block. Require `## For the planner` with wave-1
+   blockers, walking skeleton, and pitfall-to-task guidance.
+4. If structural validation fails, redispatch one complete corrected brief
+   under logical task name `decide`, following the runtime dispatch
+   contract, and validate again. If it still fails, use
+   `pipeline_state.py transition` with expected `decide/active`, exact branch
+   and archive values, `--set-status blocked`, and an event naming the failed
+   synthesis gate, and
+   present **Outcome** with the failed gate, **Review** linking SYNTHESIS.md or
+   STATE.md when it is missing, and **Next** naming the one correction or user
+   decision required; then stop.
+5. Present the decision-list outcome and a Markdown link to the resolved
+   absolute SYNTHESIS.md output path before every `NEEDS-USER`
+   item. Use an interactive user-input tool when available; otherwise ask in
+   chat and wait. Present
+   each item's options with the evidence-preferred option first, marked
+   `(recommended)` and justified in one line; a pure values call with no
+   evidence either way carries no recommendation, stated as such. For each
+   answer, append the ruling under `## User rulings`, revise every affected
+   decision so it reflects the ruling, and only then remove its tag.
+6. Re-run the structural gate. When it passes with no unresolved user items,
+   use `pipeline_state.py transition` with expected `decide/active`, exact
+   branch and archive values, `--set-phase decide --set-status done`, and an
+   event naming the validated synthesis path. Include `--project-dir
+   .project/next` in lookahead and require returned `decide/done`. Confirm the
+   settled outcome, link SYNTHESIS.md again, and name
+   the next phase: the roadmap phase in program scope, planning otherwise.
+   When routed by an active `$gsd-path`, return control to
+   that router. When invoked directly, stop and tell the user to explicitly
+   invoke `$gsd-path`, which routes to that next phase; do not invoke an
+   explicit-only sibling skill yourself.
+
+## Rules
+
+- Make commitments, not option lists. Name the runner-up and why it lost
+  when a real alternative was weighed; never invent one.
+- Cite evidence by file and finding heading for every decision.
+- Route low-confidence decisions to wave 1 for verification. Reject uncited
+  decisions.
+- Resolve evidence conflicts or escalate a true values decision; never average.

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

@@ -0,0 +1,6 @@
+interface:
+  display_name: "GSD Path Decide"
+  short_description: "Turn evidence into settled decisions"
+  default_prompt: "Use $gsd-path-decide to settle implementation decisions from the available evidence."
+policy:
+  allow_implicit_invocation: false

package/skills/gsd-path-decide/references/decider.md

@@ -0,0 +1,36 @@
+# Decider role
+
+Turn supplied research into settled decisions. Do not conduct new research.
+
+## Input and output
+
+- Require absolute paths for INTENT.md, every evidence file, SYNTHESIS.md, and
+  the synthesis template.
+- Read AGENTS.md, INTENT.md, the template, and every evidence file.
+- Write only the exact output using the template. Stop on a missing input or
+  template.
+
+## Decide
+
+1. Treat intent constraints and vetoes as hard limits.
+2. Map agreements, conflicts, and gaps across all evidence.
+3. For every genuinely open choice, select one decision, name the runner-up
+   and why it lost, and cite the evidence file and finding heading. Record a
+   choice already settled by an intent constraint or the existing codebase in
+   one line under Settled, citing the settling source; do not invent a
+   runner-up for it.
+4. Resolve conflicts by source quality and fit to intent. Preserve a user
+   values choice as `NEEDS-USER` with the genuinely viable options; never
+   guess.
+   When the evidence leans one way, order that option first with a one-line
+   reason so the checkpoint can mark it recommended; note when it is a pure
+   values call with no lean.
+5. Route decisions supported only by low-confidence evidence to wave 1.
+6. Write For the planner with wave-1 blockers, the walking skeleton, and each
+   pitfall mapped to a future task.
+7. Carry every unanswered intent question into Still unknown.
+
+Every decision requires cited evidence. Compress to decisions and rationale
+rather than re-narrating research.
+
+Return the output path, one line per decision, and the `NEEDS-USER` count.