@opengsd/gsd-path 1.1.0 → 1.3.0

package/platforms/claude/dispatch.md

@@ -27,10 +27,10 @@ Apply this contract whenever a GSD Path skill delegates work:
   a colliding target.
 - Resolve the phase's linked role brief to an absolute path. Include that path
   in the prompt and require the agent to read it before acting.
-- Tier hints: when the host advertises model or reasoning-effort selection,
-  request `heavy` for `plan`, `plan_patch`, `decide`, and `roadmap`, and
-  `light` for `inspect_docs` and `docs_audit`; when it offers no such
-  selection, do not override the model except on a review-panel child, which receives the exact slug from `scripts/review_panel.py resolve`. Do not ask Claude Code to create
+- 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. Do not ask Claude Code to create
   another worktree: GSD Path supplies the exact repository or
   linked-worktree root in the brief, and the child must work only there.
   Host isolation: none.

package/platforms/copilot/dispatch.md

@@ -26,10 +26,10 @@ Apply this contract whenever a GSD Path skill delegates work:
   never create a colliding logical target.
 - Resolve the phase's linked role brief to an absolute path. Include that path
   in the prompt and require the child to read it before acting.
-- Tier hints: when the host advertises model or reasoning-effort selection,
-  request `heavy` for `plan`, `plan_patch`, `decide`, and `roadmap`, and
-  `light` for `inspect_docs` and `docs_audit`; when it offers no such
-  selection, do not override the model except on a review-panel child, which receives the exact slug from `scripts/review_panel.py resolve`. Do not ask Copilot to create another
+- 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. Do not ask Copilot to create another
   worktree: GSD Path supplies the exact repository or linked-worktree root,
   and the child must work only there. Host isolation: none.
 - Give every child a self-contained prompt with absolute input, template, and

package/platforms/cursor/dispatch.md

@@ -3,7 +3,7 @@
 Apply this contract whenever a GSD Path skill delegates work:
 
 - Use Cursor's `Task` tool with the installed custom `gsd-path` subagent. Its
-  model is `inherit` and it has full tool access; the linked role brief supplies
+  model inherits unless the model-policy helper selects an override; it has full tool access; the linked role brief supplies
   the read-only boundary for auditors and reviewers.
 - Supply the deterministic logical task name as the task description:
   `inspect_codebase`, `inspect_docs`, `docs_audit`,
@@ -25,15 +25,10 @@ Apply this contract whenever a GSD Path skill delegates work:
   brief. If the prior child is still running, wait; never collide targets.
 - Resolve the phase's linked role brief to an absolute path. Include that path
   in the prompt and require the child to read it before acting.
-- Tier hints: when the host advertises model or reasoning-effort selection,
-  request `heavy` for `plan`, `plan_patch`, `decide`, and `roadmap`, and
-  `light` for `inspect_docs` and `docs_audit`; when it offers no such
-  selection, do not override the model. The only exception is a review-panel
-  child: pass the exact slug returned by `scripts/review_panel.py resolve`
-  for that family. Never override the model on the canonical reviewer,
-  planner, or coder. Set the task working directory to the
-  exact repository or linked-worktree root supplied by GSD Path; do not ask
-  Cursor or the child to create another worktree. Host isolation: none.
+- 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.
 - Give every child a self-contained prompt with absolute input, template, and
   output paths plus its bounded responsibility. A coder prompt also names its
   isolated linked-worktree root; no child may infer the primary worktree.

package/platforms/grok/dispatch.md

@@ -26,12 +26,10 @@ Apply this contract whenever a GSD Path skill delegates work:
   it; never create a colliding logical target.
 - Resolve the phase's linked role brief to an absolute path. Include that path
   in the prompt and require the subagent to read it before acting.
-- Tier hints: when the host advertises model or reasoning-effort selection,
-  request `heavy` for `plan`, `plan_patch`, `decide`, and `roadmap`, and
-  `light` for `inspect_docs` and `docs_audit`; when it offers no such
-  selection, do not override the model except on a review-panel child, which receives the exact slug from `scripts/review_panel.py resolve`. Set `cwd` to the exact root supplied
-  by GSD Path and use `isolation: none`; the pipeline already owns any
-  required linked worktree. Host isolation: none.
+- 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.
 - Give every subagent a self-contained prompt with absolute input, template,
   and output paths plus its bounded responsibility. A coder prompt also names
   its isolated linked-worktree root; no child may infer the primary worktree.

package/platforms/kimi/dispatch.md

@@ -27,10 +27,10 @@ Apply this contract whenever a GSD Path skill delegates work:
   brief, wait for it; never create a colliding logical target.
 - Resolve the phase's linked role brief to an absolute path. Include that
   path in the prompt and require the child to read it before acting.
-- Tier hints: when the host advertises model or reasoning-effort selection,
-  request `heavy` for `plan`, `plan_patch`, `decide`, and `roadmap`, and
-  `light` for `inspect_docs` and `docs_audit`; when it offers no such
-  selection, do not override the model except on a review-panel child, which receives the exact slug from `scripts/review_panel.py resolve`. Do not ask Kimi to create a worktree:
+- 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. Do not ask Kimi to create a worktree:
   GSD Path supplies the exact repository or linked-worktree root in the
   brief, and the child must work only there. Host isolation: none.
 - Give every child a self-contained prompt with absolute input, template,

package/platforms/kiro/dispatch.md

@@ -23,12 +23,10 @@ Apply this contract whenever a GSD Path skill delegates work:
   self-contained brief. Disk artifacts remain the source of truth.
 - Resolve the phase's linked role brief to an absolute path. Include that path
   in the prompt and require the subagent to read it before acting.
-- Tier hints: when the host advertises model or reasoning-effort selection,
-  request `heavy` for `plan`, `plan_patch`, `decide`, and `roadmap`, and
-  `light` for `inspect_docs` and `docs_audit`; when it offers no such
-  selection, do not override the model except on a review-panel child, which receives the exact slug from `scripts/review_panel.py resolve`. 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. Host isolation: none.
+- 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.
 - Give every child a self-contained prompt with absolute input, template, and
   output paths plus its bounded responsibility. A coder prompt also names its
   isolated linked-worktree root; no child may infer the primary worktree.

package/platforms/opencode/dispatch.md

@@ -28,10 +28,10 @@ Apply this contract whenever a GSD Path skill delegates work:
   source of truth.
 - Resolve the phase's linked role brief to an absolute path. Include that path
   in the prompt and require the child to read it before acting.
-- Tier hints: when the host advertises model or reasoning-effort selection,
-  request `heavy` for `plan`, `plan_patch`, `decide`, and `roadmap`, and
-  `light` for `inspect_docs` and `docs_audit`; when it offers no such
-  selection, do not override the model except on a review-panel child, which receives the exact slug from `scripts/review_panel.py resolve`. 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.
+- 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.
 - Give every child a self-contained prompt with
   absolute repository, input, template, and output paths plus its bounded
   responsibility. A coder prompt also names its isolated linked-worktree root;

package/platforms/qwen/dispatch.md

@@ -25,10 +25,10 @@ Apply this contract whenever a GSD Path skill delegates work:
   Disk artifacts, not child chat history, remain the source of truth.
 - Resolve the phase's linked role brief to an absolute path. Include that path
   in the prompt and require the child to read it before acting.
-- Tier hints: when the host advertises model or reasoning-effort selection,
-  request `heavy` for `plan`, `plan_patch`, `decide`, and `roadmap`, and
-  `light` for `inspect_docs` and `docs_audit`; when it offers no such
-  selection, do not override the model except on a review-panel child, which receives the exact slug from `scripts/review_panel.py resolve`. Do not ask Qwen Code to create another
+- 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. Do not ask Qwen Code to create another
   worktree: GSD Path supplies the exact repository or linked-worktree root,
   and the child must work only there. Host isolation: none.
 - Give every child a self-contained prompt with absolute input, template, and

package/platforms/shared-agents/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

package/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

package/scripts/archive_milestone.py

@@ -16,6 +16,9 @@ import re
 import shutil
 import subprocess
 import sys
+
+# Runtime helpers must not modify their immutable installation.
+sys.dont_write_bytecode = True
 from contextlib import contextmanager
 from datetime import date
 from pathlib import Path, PurePosixPath
@@ -1743,6 +1746,12 @@ def require_clean_active_root(active_root: Path, archive: Path) -> None:
     carried_forward = pending_ruling_count(archived_audit)
     # Persistent project metadata ships but never archives with a milestone.
     allowed = {"STATE.md", "REPOSITORY.md", "archive", "LESSONS.md", "next"}
+    for name in ("config.json", "model-policy.json"):
+        path = active_root / name
+        if path.exists() or path.is_symlink():
+            if path.is_symlink() or not path.is_file() or path.stat().st_nlink != 1:
+                raise ArchiveError(f"project settings must be a regular unlinked file: {path}")
+            allowed.add(name)
     if (active_root / "CHARTER.md").is_file():
         # Program flow: these persist at the .project/ top level.
         allowed |= {"CHARTER.md", "ROADMAP.md", "SYNTHESIS.md"}
@@ -1808,6 +1817,7 @@ def prepared_transaction(
     repo: Path,
     phases: Sequence[str],
     must_be_uncommitted: bool = False,
+    *, historical: bool = False,
 ) -> tuple:
     project = repo.resolve()
     active_root = require_project_layout(project)
@@ -1816,7 +1826,7 @@ def prepared_transaction(
     state, _, loaded_state_path = strict_state(project)
     if loaded_state_path.resolve() != state_path.resolve():
         raise ArchiveError("strict STATE.md loader returned an unexpected path")
-    require_transaction_context(project, state, phases)
+    require_transaction_context(project, state, phases, historical=historical)
 
     configured = state.archive
     if configured is None:
@@ -1880,10 +1890,11 @@ def require_canonical_commit_body(
         raise ArchiveError(f"{label} commit body does not match required fields")
 
 
-def find_ship_commit(project: Path, archive_name: str) -> str:
+def find_ship_commit(project: Path, archive_name: str, *, historical: bool = False) -> str:
     expected_subject = ship_subject(archive_name)
     log = require_git_success(
-        run_git(project, "log", "--first-parent", "--format=%H%x00%s", "HEAD"),
+        run_git(project, "log", *([] if historical else ["--first-parent"]),
+                "--format=%H%x00%s", "HEAD"),
         "inspect HEAD history for the ship commit",
     )
     matches = []
@@ -1926,19 +1937,22 @@ def validate_shipped_roadmap(text: str, state: PipelineState, archive: str) -> N
         raise ArchiveError("ROADMAP.md must record Status: shipped and the exact Archive")
 
 
-def validate(repo: Path) -> dict:
+def validate(repo: Path, *, historical: bool = False) -> dict:
     project, _, state, configured, archive, archived_files, reviewed_head = prepared_transaction(
         repo,
         ("shipped",),
+        historical=historical,
     )
     if state.status != "done":
         raise ArchiveError("STATE.md is not shipped/done")
 
-    project_status = require_git_success(run_git(project, "status", "--porcelain"), "inspect worktree status")
+    project_status = require_git_success(
+        run_git(project, "status", "--porcelain", *(["--", ".project"] if historical else [])),
+        "inspect worktree status")
     if project_status:
         raise ArchiveError("ship transaction worktree is not clean")
 
-    ship_commit = find_ship_commit(project, archive.name)
+    ship_commit = find_ship_commit(project, archive.name, historical=historical)
 
     parents = require_git_success(
         run_git(project, "rev-list", "--parents", "-n", "1", ship_commit),

package/scripts/bootstrap_repository.py

@@ -561,7 +561,14 @@ def render_state(template: Path, request: BootstrapRequest) -> str:
     )
     if "<slug>" in content or "branch: null" in content:
         raise BootstrapError("state template placeholders were not fully replaced")
-    return content
+    try:
+        from .path_config import initial_state
+    except ImportError:
+        from path_config import initial_state
+    try:
+        return initial_state(content)
+    except (OSError, ValueError, RuntimeError) as error:
+        raise BootstrapError(str(error)) from error
 
 
 def render_binding(

package/scripts/build_recovery.py

@@ -3,6 +3,11 @@
 
 from __future__ import annotations
 
+import sys
+
+# Runtime helpers must not modify their immutable installation.
+sys.dont_write_bytecode = True
+
 import json
 import re
 from pathlib import Path

package/scripts/build_state.py

@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+# gsd-path project runtime
 """Build task readiness, landing reconciliation, and the verify ledger."""
 
 from __future__ import annotations
@@ -7,6 +8,7 @@ import argparse
 import json
 import re
 import sys
+sys.dont_write_bytecode = True
 from dataclasses import dataclass
 from datetime import datetime, timezone
 from pathlib import Path, PurePosixPath

package/scripts/check_docs_audit.py

@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+# gsd-path project runtime
 """Gate a GSD Path docs audit (.project/research/DOCS-AUDIT.md) against its contract.
 
 Checks the rules the docs-audit contract states in prose: the header lines,
@@ -32,6 +33,7 @@ import json
 import re
 import subprocess
 import sys
+sys.dont_write_bytecode = True
 from datetime import date
 from pathlib import Path
 from typing import Dict, List, Optional, Sequence

package/scripts/check_handoffs.py

@@ -7,6 +7,9 @@ import json
 import re
 import subprocess
 import sys
+
+# Runtime helpers must not modify their immutable installation.
+sys.dont_write_bytecode = True
 from pathlib import Path, PurePosixPath
 from typing import Dict, List, Optional, Sequence, Set, Tuple
 
@@ -131,6 +134,9 @@ def _strict_frontmatter(text: str, label: str) -> Dict[str, object]:
     while index < len(lines):
         line = lines[index]
         if line == "---":
+            for field in ('model', 'effort'):
+                if field in values and (not isinstance(values[field], str) or not values[field].strip()):
+                    raise HandoffError(f'{label}: {field} must be a nonempty scalar or inherit')
             return values
         if not line.strip() or line.lstrip().startswith("#"):
             index += 1

package/scripts/check_task_briefs.py

@@ -6,6 +6,9 @@ import argparse
 import json
 import re
 import sys
+
+# Runtime helpers must not modify their immutable installation.
+sys.dont_write_bytecode = True
 from pathlib import Path, PurePosixPath
 from typing import Dict, List, Optional, Sequence, Set, Tuple
 

package/scripts/detect_project.py

@@ -34,6 +34,9 @@ import re
 import stat
 import subprocess
 import sys
+
+# Runtime helpers must not modify their immutable installation.
+sys.dont_write_bytecode = True
 from datetime import date
 from pathlib import Path, PurePosixPath, PureWindowsPath
 from typing import Iterable, NamedTuple, Optional, Sequence
@@ -1200,7 +1203,14 @@ def filled_state_template(template: str, slug: str, phase: str) -> str:
     text = text.replace("YYYY-MM-DD — <phase> — project initialized", stamp)
     if "<slug>" in text or "YYYY-MM-DD" in text:
         raise DetectError("state template placeholder remains")
-    return text
+    try:
+        from .path_config import initial_state
+    except ImportError:
+        from path_config import initial_state
+    try:
+        return initial_state(text)
+    except (OSError, ValueError, RuntimeError) as error:
+        raise DetectError(str(error)) from error
 
 
 def write_all(descriptor: int, payload: bytes) -> None:

package/scripts/discussion_records.py

@@ -7,6 +7,9 @@ import json
 import os
 import shutil
 import sys
+
+# Runtime helpers must not modify their immutable installation.
+sys.dont_write_bytecode = True
 from contextlib import contextmanager
 from datetime import date
 from pathlib import Path

package/scripts/discussion_validate.py

@@ -2,6 +2,11 @@
 # gsd-path project runtime
 """Validate discussion records, reviews and the manifest for archive_milestone."""
 
+import sys
+
+# Runtime helpers must not modify their immutable installation.
+sys.dont_write_bytecode = True
+
 import json
 import re
 import shutil
@@ -409,7 +414,7 @@ def remove_interrupted_carry_copy(active_root: Path, archive: Path) -> None:
 
 
 def require_transaction_context(
-    project: Path, state: PipelineState, phases: Sequence[str]
+    project: Path, state: PipelineState, phases: Sequence[str], *, historical: bool = False
 ) -> None:
     phase = state.phase
     if phase not in phases:
@@ -429,7 +434,7 @@ def require_transaction_context(
     )
     if archive_milestone.is_unset(expected_branch):
         raise ArchiveError("STATE.md does not name a bound build branch")
-    if current_branch != expected_branch:
+    if current_branch != expected_branch and not historical:
         raise ArchiveError(
             f"current branch {current_branch!r} does not match STATE.branch {expected_branch!r}"
         )
@@ -446,7 +451,7 @@ def require_transaction_context(
         ),
         "inspect non-project worktree status",
     )
-    if non_project_status:
+    if non_project_status and not historical:
         raise ArchiveError("non-.project worktree changes block the archive transaction")