@opengsd/gsd-path 1.0.0

package/skills/path/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/path/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/path/templates/answers.md

@@ -0,0 +1,29 @@
+# GSD Path Discussion — Answers
+
+<!-- Written by $gsd-path-discuss. Append one record per turn; never rewrite prior answers. -->
+
+## Answer A001 — <YYYY-MM-DD> — <topic>
+
+- **Thread**: T001
+- **Turn**: D001
+- **Supersedes**: none | A###
+- **Question**: <the question being answered>
+- **Status**: working | NEEDS-USER | final
+- **Phase/status**: <phase>/<status>
+- **Conclusion**: <answer first>
+- **Reasoning / pushback**: <why, including rejected premise or safer alternative>
+- **Evidence**: <exact repository paths and line references; commands only if run>
+- **Research**: <not needed — reason, or query, checked sources, and confidence>
+- **Confidence**: high | medium | low | unverifiable
+- **Unresolved**: <none, or NEEDS-USER / RESEARCH question>
+- **Next owner**: <none, user, or named GSD Path phase>
+- **Target artifact**: <none or canonical .project path>
+- **Follow-up**: none | required
+
+## Disposition X001 — <YYYY-MM-DD>
+
+- **Answer**: A###
+- **Status**: applied | acknowledged-no-change | superseded | rejected-by-user
+- **Owner**: <phase or router>
+- **Artifact**: <canonical path or none>
+- **Evidence**: <what was changed, why no change was needed, or the user ruling>

package/skills/path/templates/archive-manifest.md

@@ -0,0 +1,37 @@
+# Archive — <NNN>-<milestone-slug>
+
+<!-- Written at ship time by $gsd-path-ship final. The archive's table of
+     contents: a future audit must be able to reconstruct the milestone
+     from this file. Append-only once written. The validator requires
+     "Final verdict:" to be exactly the string shown below. -->
+
+Milestone: <name>
+Shipped: <date>
+Final verdict: all criteria met; project verify passed
+Waves: <n>  Tasks: <n> done / <n> total  Review cycles used: <per wave, e.g. 1/2/1>
+Carried forward: <none, or "N DOCS-AUDIT ruling(s)">
+
+## Success criteria at ship
+
+<!-- Evidence is copied verbatim from FINAL.md; escape a literal pipe as
+     \| so the row keeps its three cells. -->
+
+| Criterion | Verdict | Evidence |
+|-----------|---------|----------|
+| <criterion copied from FINAL.md> | met | <FINAL Reference; else Check; else Observed> |
+
+## Contents
+
+<!-- Every file moved into this archive, one per line, relative paths. -->
+- intent/INTENT.md
+- research/...
+- plan/PLAN.md
+- tasks/...
+- review/...
+
+## Notes
+
+<!-- Anything the next milestone should know: escalations that shaped the
+     build, accepted drift, known debt. Write at least one substantive bullet;
+     use "none" if clean. -->
+- <note>

package/skills/path/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/path/templates/codebase.md

@@ -0,0 +1,46 @@
+# Evidence — codebase
+
+<!-- Written by the codebase mapper during $gsd-path-inspect. Read by define
+     (brownfield mode), researchers (fifth standard dimension), the planner
+     (conventions are binding), and reviewers. -->
+
+Repo root: <absolute path>
+Scanned: <date>
+Checks run: <exact commands run and their results, e.g. `npm test` → 37/40 pass>
+
+## Map
+
+- **Stack**: <languages, frameworks, versions actually in use, from manifests>
+- **Entry points**: <binaries, main modules, routes — how this thing starts>
+- **Architecture**: <layers and flow in 3–5 sentences>
+- **Conventions**: <naming, error handling, test style, commit style — binding on the planner>
+- **Maturity**: <what runs, test coverage shape, what is scaffolding>
+- **Recent activity**: <where the last N commits cluster — what was being worked on>
+
+## Finding: <short claim as heading>
+
+- **Claim**: <one specific, falsifiable statement about this codebase>
+- **Source**: <file:line or command actually run>
+- **Confidence**: <high | medium | low>
+- **Why it matters here**: <what inspection/planning gets wrong without this>
+
+<!-- Record every load-bearing surprise or half-built area observed. There is
+     no minimum finding quota; explain an empty section if none were found. -->
+
+## Apparent intent
+
+<!-- Inference, clearly flagged — what the project seems to be becoming. -->
+
+- <inference> — based on <evidence>
+
+## Open questions for define
+
+<!-- What only the user can settle about this codebase. -->
+
+- <question>
+
+## Blocked areas
+
+<!-- What could not be inspected and why. "none" if clean. -->
+
+- <area> — <what blocked inspection>

package/skills/path/templates/dialogue.md

@@ -0,0 +1,21 @@
+# GSD Path Discussion — Dialogue
+
+<!-- Written by $gsd-path-discuss. Append turns; never rewrite prior turns. -->
+
+## Turns
+
+### D001 — <YYYY-MM-DD> — <phase>/<status> — <topic>
+
+- **Thread**: T001
+- **Reply to**: none | D###
+- **User (verbatim)**:
+
+  > <copy the user's message exactly>
+
+- **Assistant**:
+
+  <copy the answer returned to the user>
+
+- **Evidence checked**: <repository paths, line references, commands actually run, or none>
+- **Research**: <not needed — reason, or query/sources/confidence>
+- **Thread status**: working | NEEDS-USER | final

package/skills/path/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/path/templates/evidence.md

@@ -0,0 +1,24 @@
+# Evidence — <dimension>
+
+<!-- Written by one researcher role. Consumed by the decider. -->
+
+Dimension: <domain | stack | pitfalls | similar | custom>
+Questions assigned: <exact RESEARCH questions joined by "; ", or "none">
+
+## Finding: <short claim as heading>
+
+- **Claim**: <one specific, falsifiable statement>
+- **Source**: <URL / doc / repo path actually opened>
+- **Confidence**: <high | medium | low>
+- **Why it matters here**: <one line tying this to INTENT.md>
+
+<!-- One block per load-bearing finding — no quota. Repeat as needed. -->
+
+## Assigned questions — answers
+
+- <question> → <answer with source, or "no reliable source found">
+
+## Dead ends
+
+<!-- What was checked and didn't pan out, so nobody re-treads it. -->
+- <path explored> — <why it's a dead end>

package/skills/path/templates/final-review.md

@@ -0,0 +1,27 @@
+# Final Review — <project name>
+
+<!-- Authorship and evidence reuse follow the ship phase contract. Each INTENT.md success
+     criterion appears exactly once and carries checked evidence. A criterion
+     listed in PLAN.md's Surface contract also names its Surface, and its
+     Check is the walkthrough performed — never internal test output. Embedded
+     angle brackets are valid in concrete Check and Observed values. -->
+
+Reviewed HEAD: <full SHA>
+Overall verdict: <pass | blocked>
+
+<!-- pass only when every criterion is met; blocked when any criterion is
+     not-met or unverifiable. -->
+
+## Success criteria
+
+### SC1 — <criterion copied verbatim from INTENT.md>
+
+- **Verdict**: <met | not-met | unverifiable>
+- **Surface**: <the surface PLAN.md's Surface contract lists this criterion under; omit the whole field for any other criterion>
+- **Check**: `<command actually run, or "none">`
+- **Observed**: <relevant output or observed behavior>
+- **Reference**: <file:line, artifact path, or "none">
+- **Finding**: <none, or what was found instead>
+- **Fix direction**: <none, or concrete direction for a patch task>
+
+<!-- Repeat once per success criterion, preserving INTENT.md order. -->

package/skills/path/templates/gap-review.md

@@ -0,0 +1,20 @@
+# Gap Review — <N>: <risk identity>
+
+<!-- Written by one final gap reviewer. This file covers exactly one
+     cross-wave integration risk named in the review brief. -->
+
+Reviewed HEAD: <full SHA>
+Gap verdict: <pass | blocked>
+Risk: <same risk identity as the heading>
+Waves checked: <wave numbers>
+
+## Checked evidence
+
+- **Check**: `<command actually run, or "none">`
+- **Observed**: <relevant output or observed behavior>
+- **Reference**: <file:line, artifact path, or "none">
+
+## Finding
+
+- **Found**: <evidence-backed result>
+- **Fix direction**: <none when pass; concrete direction when blocked>