@opengsd/gsd-path 1.0.0 → 1.2.0

package/skills/gsd-path-forensics/scripts/worktree_paths.py

@@ -0,0 +1,94 @@
+#!/usr/bin/env python3
+# gsd-path project runtime
+"""Placement shared by task isolation, verification, and integration."""
+
+import sys
+
+# Runtime helpers must not modify their immutable installation.
+sys.dont_write_bytecode = True
+
+import hashlib
+import json
+import os
+import tempfile
+from pathlib import Path
+
+try:
+    import _common
+except ImportError:
+    from scripts import _common
+
+
+def _git(primary: Path, *args: str) -> str:
+    result = _common.run_git(primary, *args)
+    if result.returncode:
+        raise ValueError(result.stderr.strip() or "cannot inspect worktree placement")
+    return result.stdout.rstrip("\n")
+
+
+def _identity(path: Path) -> str:
+    return hashlib.sha256(os.fsencode(path)).hexdigest()
+
+
+def _workspace(primary: Path, pin: bool) -> Path:
+    common = Path(_git(primary, "rev-parse", "--git-common-dir"))
+    common = (primary / common).resolve()
+    identity = _identity(primary)
+    receipt = common / "gsd-path" / "workspaces" / f"{identity}.json"
+    try:
+        data = json.loads(receipt.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        pass
+    else:
+        if (not isinstance(data, dict) or data.get("primary") != str(primary)
+                or not isinstance(data.get("root"), str)
+                or not Path(data["root"]).is_absolute()):
+            raise ValueError(f"invalid worktree placement receipt: {receipt}")
+        return Path(data["root"])
+
+    root = Path(os.environ.get("GSD_PATH_WORKTREE_ROOT") or Path.home() / ".gsd-path" / "projects").expanduser()
+    if not root.is_absolute():
+        raise ValueError("GSD_PATH_WORKTREE_ROOT must be absolute")
+    root = root.resolve()
+    parent = root
+    while not parent.exists():
+        parent = parent.parent
+    ancestor = _common.run_git(parent, "rev-parse", "--git-common-dir")
+    same_repository = (
+        ancestor.returncode == 0
+        and (parent / ancestor.stdout.strip()).resolve() == common
+    )
+    if root.is_relative_to(primary) or same_repository:
+        raise ValueError(f"managed worktree root must be outside this repository's worktrees: {root}")
+    workspace = root / _identity(common) / identity
+    if pin:
+        receipt.parent.mkdir(parents=True, exist_ok=True)
+        fd, temporary = tempfile.mkstemp(dir=receipt.parent)
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as handle:
+                json.dump({"primary": str(primary), "root": str(workspace)}, handle)
+            try:
+                os.link(temporary, receipt)
+            except FileExistsError:
+                return _workspace(primary, False)
+        finally:
+            os.unlink(temporary)
+    return workspace
+
+
+def worktree_path(primary: Path, kind: str, name: str, *, pin: bool = False) -> Path:
+    primary = primary.resolve()
+    if kind not in {"task", "verify", "integrate"} or not name or Path(name).name != name or name in {".", ".."}:
+        raise ValueError("invalid managed worktree kind or name")
+    legacy = (primary.parent / f".{primary.name}-gsd-path-integrate-{name}"
+              if kind == "integrate" else primary.parent / f"{primary.name}.gsd-path" / kind / name)
+    branch = f"refs/heads/gsd-path-{kind}/{name}"
+    records = _git(primary, "worktree", "list", "--porcelain", "-z").split("\0\0")
+    for record in records:
+        fields = record.split("\0")
+        if f"worktree {legacy}" in fields and f"branch {branch}" in fields:
+            return legacy
+    # Keep collision checks and missing-directory recovery at the old location.
+    if os.path.lexists(legacy):
+        return legacy
+    return _workspace(primary, pin) / kind / name

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

@@ -3,6 +3,8 @@ name: gsd-path-inspect
 description: Inspect an existing codebase and its documentation to establish brownfield ground truth before intent is defined. Use only when the user explicitly invokes $gsd-path-inspect or an active $gsd-path router explicitly routes to this phase.
 ---
 
+Before executing project helpers, read [runtime selection](references/runtime-selection.md).
+
 # GSD Path Inspect Phase
 
 Establish ground truth about an existing project before intent is defined.
@@ -21,10 +23,12 @@ phase blocks.
 
 If STATE.md is missing, run the bundled
 `python3 <absolute-bundled-script> initialize --repo <absolute-root>
---template <absolute-state-template>` helper (`scripts/detect_project.py`) and
+--template <absolute-state-template> --require-git` helper (`scripts/detect_project.py`) and
 follow its returned JSON `verdict` / `route`. This is the only no-state
 boundary; do not run `classify` first or classify from a directory listing or
-conversation. If the command exits nonzero, returns `error`, or returns
+conversation. Handle `route: setup-repository` before the write gate: preserve
+the folder unchanged and return to `$gsd-path` for repository setup; no state
+was written. If the command exits nonzero, returns `error`, or returns
 `wrote_state: false`, report the error and block without routing or claiming
 STATE.md was written.
 - `owned` — continue under the existing-state rules below.
@@ -47,6 +51,31 @@ same milestone; a later milestone's `inspect/active` is a new scan.
 
 ## Process
 
+For an initial `inspect/active` inspection on the `.project` track, with neither output
+artifact present and a clean Git product at the recorded HEAD, run the bundled
+`python3 <absolute workflow_run.py> prepare-inspect --repo <absolute root>
+--expected-head <recorded HEAD>` first. It performs the inventory freeze and
+both sidecar preparations from steps 1–2 and writes complete assignment briefs.
+Its state validation and pending-answer check satisfy those entry checks;
+reuse their results at this boundary.
+Use its returned `inspection.inventory_file` for the gate. Before dispatch, read
+and apply the [runtime dispatch contract](references/dispatch.md), including its
+host-specific context isolation. Dispatch each returned logical `task_name` in a fresh context with its `brief_file` path and the current
+user constraints, including configured budgets. The child reads that file;
+the parent does not read or rewrite the roles, templates, or generated briefs.
+When both children return, review the mapper's Map and Findings against its
+template as in step 3. After that review passes, run the bundled
+`python3 <absolute workflow_run.py> finish-inspect --repo <absolute root>
+--expected-head <recorded HEAD> --inspection <returned receipt_file>
+--mapper-reviewed`. This runs the docs gate, checks the audit baseline,
+collects and retires both sidecars, checks pending discussion, and records
+`inspect/done` through the canonical transition. Do not repeat those operations.
+Present step 4's ground truth and use step 5's caller handoff. A failure uses
+step 3's failure contract and the returned step evidence; do not blindly rerun
+the completion command or repeat already proven steps.
+Prior evidence, lookahead, or a dirty/non-Git product uses steps 1–2 below.
+Preparation never changes phase state; neither command dispatches agents.
+
 1. Before creating or changing `.project/` Markdown, freeze the helper's exact
    stdout from `python3 <absolute check_docs_audit.py> --repo <absolute root>
    --emit-inventory` in a temporary file. Do not rediscover or edit that
@@ -132,12 +161,7 @@ same milestone; a later milestone's `inspect/active` is a new scan.
    <current branch or null> --expect-archive <current archive or null>
    --set-phase inspect --set-status done`. This helper is the only ordinary
    STATE mutation; require its returned state to be `inspect/done`.
-   Identify `$gsd-path-define` as next. When this phase was routed by an
-   active `$gsd-path`, return control to that router so its bundled define
-   contract runs in brownfield mode (and milestone mode when ROADMAP.md
-   exists). When invoked directly, stop and tell the
-   user to explicitly invoke `$gsd-path`, which routes to define; do not invoke
-   an explicit-only sibling skill yourself.
+   Use the executable phase handoff in AGENTS.md.
 
 ## Lookahead mode
 

package/skills/gsd-path-inspect/references/dispatch.md

@@ -7,10 +7,7 @@ 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.
+  `followup_task`.
 - 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.
@@ -26,7 +23,7 @@ use exactly one matching branch:
   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
+  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`
@@ -65,20 +62,10 @@ For every branch:
 - 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.
+- Model selection: before every child launch or continuation, follow
+  [the model-policy contract](model-policy.md) and apply its recorded
+  native arguments. It owns defaults, project settings, task overrides,
+  capability failures, and reassignment. Host isolation: none. Use the exact GSD Path supplied root; create no extra checkout.
 - 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
@@ -122,6 +109,12 @@ 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.
+When the verified CLI adapter reports cumulative counters across `resume`, record
+each later invocation with `--previous-events <previous recorded CLI events>`.
+The helper checks thread identity and records only the new output, preserving the
+raw total and predecessor. Keep that chain in order; never sum cumulative totals.
+Use ordinary `record` for per-invocation counters. An unknown counter convention
+is unproven usage, not permission to guess.
 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

package/skills/gsd-path-inspect/references/docs-auditor.md

@@ -24,6 +24,20 @@ actually does. Read-only: change nothing outside your single output file.
    `## Descriptive docs` list — never its own section, never skipped.
 2. **Extract claims** — statements reality can contradict: commands,
    features, structure, status/checkboxes, config, integrations.
+   Scope each claim to this repository's product. An exclusion is a scope
+   boundary, not an evidence gap: do not create `unverifiable` findings or
+   remediation rows for the implementation of an excluded dependency. In an
+   application that installs GSD Path, descriptions of GSD Path's source
+   distribution and pipeline internals are such dependency claims. In GSD
+   Path's own source repository, they are product claims and must be audited.
+   Keep application commands, configuration, and integration promises in
+   scope even when they use a dependency. In a mixed document, audit those
+   product claims; if none remain, list its exact inventory path alone in
+   Descriptive docs. Put a short scope reason in a separate paragraph, never
+   on a path bullet. Remediation Doc cells also use exact inventory paths;
+   copy each non-verified Claim cell verbatim into its remediation row, and
+   put line numbers in Evidence. This never exempts instructions from being
+   followed or conflicting instructions from being surfaced.
 3. **Verify each claim** by the cheapest sufficient method: run the
    command, read the named code, run the relevant test, check git history.
    Record the evidence (file:line, or command + result) with the verdict:

package/skills/gsd-path-inspect/references/model-policy.md

@@ -0,0 +1,139 @@
+# Dispatch model policy
+
+Before native dispatch, run the bundled `scripts/model_policy.py`. CLI dispatch
+uses the same resolver inside `dispatch_driver.py`. The helper owns model and
+effort decisions; apply its output instead of choosing again in prose.
+
+## Project choices
+
+Use `<repo>/.project/model-policy.json`, including when the active track is
+`.project/next`. This file owns project overrides. It is not phase status.
+No file is required to retain existing behavior. `path config` can also set user
+defaults in `~/.gsd-path/config.json` under `models`. Project common roles override
+user host and common roles. Within each scope, host roles override common roles.
+Task overrides still win, and recorded assignments stay pinned.
+
+```json
+{
+  "roles": {"coder": {"model": "inherit"}},
+  "hosts": {"codex": {"plan": {"effort": "high"}}}
+}
+```
+
+Values are exact advertised model/effort strings or `inherit`. This example
+illustrates configuration; it is not a cost-saving preset. Set concrete models
+only from the current host's advertised choices. Host-specific role settings
+override common role settings. Task settings override both, independently for
+model and effort; omitted fields retain the next applicable value. Explicit
+`inherit` removes that field's override. There are no automatic fallbacks.
+
+Role keys are `coder`, `reviewer` (wave, final, and gap review), `review_panel`,
+`skeptic`, `inspect_codebase`, `inspect_docs`, `docs_audit`, `research`, `decide`,
+`roadmap`, `plan`, and `plan_patch`. Use the logical task name as the assignment,
+not as the role. Keep each panel family and review lens a distinct assignment.
+
+The helper retains heavy effort hints for plan, plan_patch, decide, and roadmap;
+light hints for inspect_docs and docs_audit; otherwise effort inherits. Codex
+maps these hints to high/low. Other hosts use only advertised equivalents.
+Hints are conditional; unsupported explicit settings stop the affected child.
+
+Coders may have scalar `model:` and `effort:` fields in their task frontmatter.
+These are part of the approved task contract. Pass the task file with `--task`.
+For other roles, pass assignment-specific `--model` or `--effort` when the owner
+explicitly overrides the role choice. Coder settings do not affect reviewers.
+
+## Advertised capabilities
+
+Capture the current child tool's schema and advertised choices in a JSON file
+outside the product tree. For each supported control, provide its native field,
+allowed values, and, for CLI dispatch, its documented argument template. Omit
+unsupported controls. The values below are fixture examples, not a host catalog:
+
+```json
+{
+  "host": "codex",
+  "model": {"field": "model", "values": ["example-model"],
+            "args": ["--model", "{value}"]},
+  "effort": {"field": "reasoning_effort", "values": ["low", "high"],
+             "args": ["-c", "model_reasoning_effort={value}"]}
+}
+```
+
+`effort_hints` may map heavy/light to exact advertised equivalents. Supply
+`inherited_model` only when the host exposes its identity. Never infer models,
+fields, or CLI flags from a host name. Every existing host uses this contract,
+including hosts with no model or effort controls. Their explicit unsupported
+settings block; their default inheritance remains usable.
+
+## Native lifecycle
+
+Resolve the bundled helper to an absolute path. Use one record under the Git
+common directory's `gsd-path/model-selection/` directory per assignment. Scope
+the path and `--scope` to the milestone, active/lookahead track, and review cycle
+where applicable; later work must not reuse an earlier record.
+
+```text
+python3 -B <helper> resolve --repo <primary> --scope <milestone/track/cycle> --assignment <logical-name> --role <role> --record <absolute-record> --capabilities <advertised-json>
+```
+
+Only `status: ready` authorizes launch. Apply `selection.native` exactly to
+the advertised child tool, preserving the host adapter's other controls and
+GSD Path task isolation. The recorded selection applies to a fresh child too.
+If an existing child is still active, reattach or send its continuation;
+resolving again does not authorize launching a second copy. When a host cannot
+change model/effort on a resumed child, a changed selection requires a fresh
+child after terminal completion of the earlier one.
+
+After terminal completion, release the assignment with `release` using the
+same identity arguments and `--terminal-result <host-completion-evidence>`.
+To change the selection, use `reassign` with the same identity, current
+capabilities, explicit model/effort changes, and `--ruling <verbatim-owner-ruling>`.
+It requires an inactive assignment and preserves prior selection history.
+Resolve again before starting the replacement. A project-policy edit alone
+does not change an existing selection. Task-contract edits still require their
+legal pipeline path.
+
+For panel children, first resolve membership with `review_panel.py resolve`,
+passing `--parent-slug` when known and repeating `--exclude-family` for every
+known parent and canonical-reviewer family (including all deep review lenses).
+Apply these exclusions before persisting membership. Detected membership skips
+excluded families; explicitly named conflicts block. Pass its selected model through `--panel-model`, and pass `--panel-family` plus
+`--exclude-family` for known parent and
+canonical-reviewer families. Persist and reuse the panel roster. Policy cannot
+waive family independence or change canonical review authority. A changed
+panel roster requires a new legal review assignment.
+
+Requested controls are durable evidence. When the host hides the inherited
+model identity, exact effective-model continuity across fresh children remains
+unproven; report that limitation rather than asserting an identity.
+
+## CLI lifecycle
+
+Pass `--model-capabilities <advertised-json>` to the driver. Commands use whole
+argument slots `{model_args}` and `{effort_args}`; the resolver expands these
+to argument arrays. They are not shell substitutions. Remove fixed model and
+effort flags when using these slots; conflicting controls block dispatch.
+Commands with explicit policy choices must expose the corresponding slots,
+including when an explicit choice is `inherit`. Unconfigured legacy commands
+without a capability file retain their existing behavior.
+An existing legacy assignment with no recorded selection keeps its saved
+command across retries, even if project policy or capabilities are later added.
+It cannot use `reassign-model`; model controls require a new explicit assignment.
+
+Review and skeptic commands accept `--model` and `--effort` for that assignment.
+For distinct panel families or review lenses, pass `--model-overrides <json>`:
+a mapping from exact logical assignment names to model/effort objects. Each
+entry applies only to its named assignment; conflicting explicit inputs block.
+A common panel model must satisfy every selected family, so use these scoped
+overrides when families need different models. Family checks remain mandatory.
+Coders read their task overrides. Panels with capabilities use the argument
+slots; legacy panel commands may retain their existing `{model}` placeholder.
+
+The driver persists selection before launch and retains it on retry. Use
+`dispatch_driver.py reassign-model --repo <primary> --task-id <logical-name>
+--model-capabilities <advertised-json> --model <slug> --ruling <owner-ruling>`
+for an inactive unfinished assignment. Finished work and pinned panel rosters
+require a new legal assignment. Earlier attempt evidence is retained.
+
+Compare total cost only with observed usage and outcomes, including retries.
+These controls do not establish cost savings, pricing, or quality rankings.

package/skills/gsd-path-inspect/references/runtime-selection.md

@@ -0,0 +1,25 @@
+# Project runtime selection
+
+Before running a project runtime helper, check for
+`<absolute-project>/.gsd-path/runtime.json`. When present, run the stable launcher:
+
+```sh
+python3 -B <absolute-project>/.gsd-path/status_runtime.py --repo <absolute-project> --runtime-path
+```
+
+Use `python` only when it is the compatible Python 3.9+ interpreter. A failure
+stops helper execution: follow the exact-version restore action in the error.
+Do not install, upgrade, or fall back to the current plugin's runtime implicitly.
+
+The returned directory is the verified Project runtime. Resolve helper names
+present in its `manifest.json` from that directory, including status, state,
+isolation, integration, archive, recovery, build-state, final-verification, and guard helpers.
+The workflow runner resolves its subprocess helpers from this same directory;
+helper imports stay within the selected runtime. This rule overrides
+references to bundled copies of those helpers. Other skill helpers, templates,
+and role briefs remain in the installed skill bundle. Pass `-B` to Python helper
+invocations so execution does not create bytecode in the runtime store.
+
+With no declaration, retain the legacy helper lookup. An existing
+`.gsd-path/runtime/` requires the explicit `--runtime-migrate --project PATH`
+operation before adopting external storage; review the resulting Git diff.

package/skills/gsd-path-inspect/scripts/_common.py

@@ -9,6 +9,11 @@ consuming module keep working.
 
 from __future__ import annotations
 
+import sys
+
+# Runtime helpers must not modify their immutable installation.
+sys.dont_write_bytecode = True
+
 import json
 import os
 import re