@opengsd/gsd-path 1.4.0 → 1.6.0

package/DOCS.md

@@ -36,6 +36,7 @@ DOCS.md (here)     four journeys in one place
 | **Team** — pin skills in repo | `--local` install; see [Installing](#installing) |
 | **Shipping broke** — archive commit blocked | [HOOKS.md](HOOKS.md) (expected with hooks) |
 | **Several repos** — one milestone changes them all | [Multi-repo milestones](README.md#multi-repo-milestones) |
+| **Several people** — one project | [Working with more than one person](FULL.md#working-with-more-than-one-person) |
 
 ---
 
@@ -101,9 +102,9 @@ README's Windows notes). **Always** restart the agent session after install.
 
 Full roots and invocation table: [README.md](README.md#install-summary).
 
-**Python installer:** `scripts/install.py` supports global and `--local`
-installs plus `--update`. The Node CLI remains the interactive wizard and npm
-entry point.
+**Python installer:** `scripts/install.py`; see
+[README.md](README.md#install-summary) for what it supports. The Node CLI
+remains the interactive wizard and npm entry point.
 Help: `node scripts/install.mjs --help`
 
 ---
@@ -247,8 +248,10 @@ resolved Git common directory and primary path, so separate clones and
 primary folders do not share a location.
 
 The first allocation pins the workspace location in
-`<git-common-dir>/gsd-path/workspaces/<workspace-id>.json`. Later environment
-changes do not move it. Existing sibling worktrees remain at their original
+`<git-common-dir>/gsd-path/workspaces/<workspace-id>.json`. Environment
+changes do not move it while a linked worktree remains. When a sidecar is
+retired and no linked worktree remains, Path removes the pin, and the next
+allocation reads `GSD_PATH_WORKTREE_ROOT` again. Existing sibling worktrees remain at their original
 paths and retain the same recovery and cleanup checks. These folders contain
 active work and evidence; they are not a disposable cache. Relocation needs
 a separate migration; do not edit placement records or move folders manually.
@@ -397,6 +400,14 @@ the supplied package's runtime and its compatible status launcher. Review those
 configuration changes before committing them. Existing versions remain available
 for other projects and branches.
 
+To record where a patched runtime came from, add `--runtime-provenance-source`,
+`--runtime-provenance-patch`, or `--runtime-provenance-note` to
+`--runtime-upgrade`. The values are written to the `provenance` object
+(`source`, `patch_ref`, `note`) in `.gsd-path/runtime.json`. Without a patch
+value, a source root that is a Git checkout records its `HEAD` commit. A later
+upgrade without these flags keeps the object only when the digest is unchanged.
+Provenance is a record only; it does not change the digest or runtime validation.
+
 A new machine needs the selected runtime installed before status and guards can
 run. `gsd-path --runtime-restore --project /absolute/project --source-root
 /path/to/matching/package` restores that exact version without changing project

package/FULL.md

@@ -8,7 +8,8 @@ Complete walkthrough from install to shipped milestone.
 
 **Contents:** [What it is](#what-gsd-path-is) · [Installation](#installation) ·
 [Starting a milestone](#starting-a-milestone) · [Phases](#phases-and-your-role) ·
-[Shipping](#shipping) · [Resume](#resume-and-recovery) · [Troubleshooting](#troubleshooting)
+[Shipping](#shipping) · [Resume](#resume-and-recovery) ·
+[More than one person](#working-with-more-than-one-person) · [Troubleshooting](#troubleshooting)
 
 **Related docs**
 
@@ -86,8 +87,8 @@ Use the [router and phase invocation table](README.md#install-summary) for your
 - **Python 3.9+** found as `python3`, `python`, or `py -3`; required for project
   installs, project refresh, and project-state
   doctor checks; optional for global-only Node installs. `scripts/install.py`
-  mirrors global and `--local` install transactions and `--update`; it does not
-  provide the interactive wizard
+  does not provide the interactive wizard; see
+  [README.md](README.md#install-summary) for what it supports
 
 ### Global install (default)
 
@@ -106,7 +107,7 @@ node scripts/install.mjs --codex --claude --cursor
 
 | Flag | Skills root |
 | --- | --- |
-| `--codex`, `--zed` | `~/.agents/skills` (shared bundle) |
+| `--codex`, `--zed`, `--muse` | `~/.agents/skills` (shared bundle) |
 | `--claude` | `~/.claude/skills` |
 | `--grok` | `~/.grok/skills` |
 | `--opencode` | OpenCode config `skills/` |
@@ -176,7 +177,7 @@ also print a one-line update notice (24h cache, fail-silent).
 - Validates synchronized package before writing
 - Uses the [managed-skill backup and collision rules](UPDATE.md#what-auto-updates)
 - Rolls back **all** selected targets if any one fails
-- Codex, Antigravity, and Zed share one local physical root — installed once
+- Codex, Antigravity, Zed, and Muse share one local physical root — installed once
   with a shared host-aware bundle
 
 Restart the host session after install if skills do not appear.
@@ -328,7 +329,11 @@ approve **Archive and ship**, the archive transaction begins:
 
 Direct integration is the project default. Before build, ask the router to set
 `pull-request` as the project default or as an override for the current
-milestone. The setting locks when build starts.
+milestone. The setting locks when build starts. When origin is not GitHub.com
+and `main` accepts merge requests only, set `external-landing`: Path publishes
+the milestone branch, you merge it in your own forge with the merge message
+that Path returns, and Path then validates the merge and tags it. See
+[integration](WORKFLOW.md#integration).
 
 After `validate-integrated` passes, the next milestone starts clean on a new
 `gsd-path/M00N` cut from `origin/main`. Invoke the router again; brownfield
@@ -407,6 +412,61 @@ in force; see [the collection helper](scripts/isolation.py).
 
 ---
 
+## Working with more than one person
+
+One operator drives a milestone. One checkout holds the bound branch
+`gsd-path/M00N` and the `.project/` state of that milestone. A multi-repo
+milestone does not change this: one coordinator checkout holds the state.
+
+GSD Path does not record or check who approves a gate. The `STATE.md` log
+keeps the date, the phase, and the event. The only name is the Git author of a
+checkpoint commit, and GSD Path does not read it. Agree in your team who
+approves.
+
+**Supported**
+
+- One person runs the router and approves the gates, in one checkout.
+- Other people review and merge the result. Set `pull-request` integration
+  before build. Path opens the pull request and waits until a GitHub user
+  account merges it with a merge commit. Path does not check which user. With
+  `external-landing`, the review is the merge request in your own forge.
+- A second session in the same checkout can ask for status and can run the
+  discussion skill. Status only reads. The discussion helper takes a lock and
+  only appends records.
+- The desktop app and the monitor only read a watched project in the
+  background. Their explicit actions change install and configuration files.
+  They cannot advance a phase. See [daemon/README.md](daemon/README.md).
+
+**Not protected**
+
+- The locks are file locks on one computer, in one clone. They put helper
+  calls in sequence: state changes, approvals, discussion records, and
+  dispatch driver calls. A state change from an old view fails with
+  `expected state does not match`. A second dispatch driver call returns
+  `blocked`.
+- The locks do not cover the files that agents write: the artifacts in
+  `.project/` and the product files. Two sessions that do phase work in one
+  checkout write to the same working tree.
+- The locks do not reach a second clone. Each clone keeps its own `STATE.md`,
+  task landings, and approvals. GSD Path does not merge them. Ship stops
+  (`moved or collides`) when `origin` already has `gsd-path/M00N` from another
+  clone.
+- You cannot share a milestone in progress through the remote. With
+  [guard hooks](HOOKS.md) installed, the pre-push hook refuses `gsd-path/M00N`
+  before its ship commit. It also refuses any other branch that carries the
+  unfinished state. Hooks are optional and local to each clone. A clone
+  without hooks has no such check.
+
+**Do not**
+
+- Do not run the router or a phase skill for one milestone from two clones, or
+  from two sessions at the same time.
+- Do not push `gsd-path/M00N` by hand, and do not merge another branch into
+  it.
+- Do not squash or rebase the integration pull request or merge request.
+
+---
+
 ## Standalone docs audit
 
 `/gsd-path-docs-audit` runs between phases as a drift check. Findings get
@@ -432,6 +492,7 @@ your skills:
 | Antigravity | `invoke_subagent` | |
 | Cursor | `Task` | installed `gsd-path` subagent |
 | Zed | `spawn_agent` | |
+| Muse Code | `muse.subagent_spawn` | trusted workspace required |
 | Kiro | subagent facility | |
 | Kimi | `Agent` | `coder` child type |
 

package/HOOKS.md

@@ -77,6 +77,29 @@ setups (Husky and friends) and linked worktrees (where `.git` is a file).
 Every selected host requires an initialized repository with a resolvable hooks
 directory; otherwise installation stops before writing.
 
+### Existing Git hooks
+
+A repository can already have its own `pre-commit`, `commit-msg`, or `pre-push`
+hook.
+
+- **In the repository's own `.git/hooks`:** the installer keeps your hook as
+  `<hook>.gsd-path-chained` and writes the guard hook in its place. The guard
+  runs first. Your hook runs after it, with the same arguments and the same
+  `pre-push` input, only when the guard accepts. If the installation fails,
+  your hook is put back unchanged.
+- **In a `core.hooksPath` directory (for example Husky) or a linked worktree:**
+  the installer stops with `cannot chain` and changes nothing. That directory
+  can be tracked or shared, so a rename there reaches other clones. Rename your
+  hook to `<hook>.gsd-path-chained` yourself, then rerun the installer. Commit
+  the rename when the directory is tracked.
+- **`<hook>.gsd-path-chained` already exists beside a foreign hook:** the
+  installer stops. Decide which of the two files you want to keep.
+
+Git hooks are local to a clone. A bot that merges on the server, such as
+Renovate, never runs them, and its commits on the default branch do not
+disturb milestone validation. A merge request can still conflict when the bot
+and the milestone change the same file; Path does not resolve that conflict.
+
 Git hooks work for **any** agent that commits. Native guard wiring denies a tool
 call when its event is malformed or the guard cannot validate it.
 
@@ -128,12 +151,50 @@ See [UPDATE.md](UPDATE.md).
   the archive tree; shell operands count an ancestor only for deletion or move
   commands
 - `git reset --hard`, destructive `git clean` modes, force pushes (including
-  `+` refspecs), destructive branch or ref deletion, `git branch -m`,
-  `git worktree remove --force`, `git stash drop`/`clear`, and whole-tree
+  `+` refspecs), `git branch -m`, `git stash drop`/`clear`, and whole-tree
   `git checkout -- .`/`git restore .`
+- forced branch deletion (`git branch -D`), `git update-ref` deletion, and
+  `git worktree remove --force` when the target is Path-owned: a `gsd-path/`,
+  `gsd-path-task/`, `gsd-path-verify/`, or `gsd-path-integrate/` branch, a
+  `refs/gsd-path/` ref, the bound `STATE.branch`, a task branch or worktree
+  that task frontmatter records, a worktree on one of these branches, and a
+  worktree below a managed worktree root (`~/.gsd-path`,
+  `GSD_PATH_WORKTREE_ROOT`, a pinned workspace root, or the earlier
+  `<repo>.gsd-path/` and `.<repo>-gsd-path-integrate-*` locations beside the
+  repository). The text `gsd-path` in a path does not make a worktree
+  Path-owned. Also Path-owned: the remote-tracking ref of one of these
+  branches (`origin/gsd-path/M001`), `refs/stash`, and a name that differs
+  from a recorded branch only in letter case. Other branches, refs, and
+  registered worktrees are allowed in each pipeline state. These three
+  commands are also denied when the guard cannot prove the target: a missing,
+  non-literal, or unregistered target, a shell parameter in the Git command
+  (`git -C "$dir" branch -D x`), a `~` or glob in a Git option value,
+  `update-ref --stdin`, an `update-ref` name outside `refs/` (`HEAD`) or an
+  option cluster (`-dm`), an `update-ref` deletion without `--no-deref` after
+  another Git command in the same command line, ownership metadata it cannot
+  read, a working directory that does not exist yet, or an `env` wrapper that
+  resets or unsets `HOME`, `XDG_CONFIG_HOME`, or a `GIT_*` variable. They are
+  denied too after a directory change the guard cannot model. Only
+  `cd <directory>` or `cd -- <directory>` is modeled, with one literal
+  directory that is absolute or starts with `./` or `../` (a shell with
+  `CDPATH` looks for a plain relative name in other directories). Another
+  command name (`pushd`, `chdir`), an option, a second operand, a redirection,
+  a `cd` in a subshell, pipeline, condition, function, alias, trap, or
+  comment line is not modeled. Use `git -C <directory>` there. A plain
+  redirection on the Git command (`2>/dev/null`, `>file`, `>>file`, `<file`,
+  `2>&1`, `&>file`) is not a target. A here-document, here-string, process
+  substitution, a redirection target that is not one literal word, or a
+  `# comment` after the command keeps the denial. So does a file
+  descriptor word of more than one digit or a `{name}` word against a
+  redirection (`10>file`, `{fd}>file`), because bash and zsh read that word
+  differently. With
+  such an `env` wrapper, or in a directory that does not exist yet, a Git
+  command that is not a built-in command is denied too, because its alias
+  cannot be inspected
 - shell writes (redirections, `tee`, `cp`, `mv`, `rm`, `sed -i`, ...) that
   target a routing control (`.git`, `.project/STATE.md`, `.project/next`,
-  `.gsd-path`) while `.project/STATE.md` exists
+  `.gsd-path`) while `.project/STATE.md` exists, or target a product file
+  outside the routed build phase (same rule as direct file-edit tools)
 - repeated assignments to the same shell variable within one command; split
   these into separate tool calls so write targets can be resolved
 - copies whose destinations, including nested recursive-copy entries, resolve
@@ -145,7 +206,8 @@ See [UPDATE.md](UPDATE.md).
   source trees containing directory symlinks are denied; use literal directory
   paths and copy directory links separately
 - shell commands that reference the archive unless the whole command is a
-  recognized standalone read or a single-command invocation of the bundled
+  recognized standalone read, a pipeline in which each segment is a recognized
+  read, or a single-command invocation of the bundled
   `pipeline_state.py` / `archive_milestone.py` helper, resolved to a regular file
   inside the verified runtime selected by `.gsd-path/runtime.json` (legacy projects use `.gsd-path/runtime/` beside `guard_hook.py`
   in the repository layout), using exactly `python` or `python3` with optional
@@ -161,11 +223,93 @@ See [UPDATE.md](UPDATE.md).
 - deletion or move commands outside a single simple segment, including command
   chains, pipes, newlines, grouping, directory changes, and command substitution
 - deletion or move commands with any argument outside the literal-path character
-  set: ASCII letters, digits, `.`, `_`, `-`, and `/` (plus a drive prefix and
-  backslashes on Windows). One matching pair of surrounding quotes is allowed;
-  spaces, parameters, wildcards, braces, and tilde paths are denied even when
-  quoted. This also applies to `find -delete` and supported destructive aliases
+  set: ASCII letters, digits, `.`, `_`, `-`, `/`, and ASCII spaces inside one
+  shell unit (plus a drive prefix and backslashes on Windows). One matching
+  pair of surrounding quotes is allowed; parameters, wildcards, braces, and
+  tilde paths are denied even when quoted. This also applies to
+  `find -delete` and supported destructive aliases
 - destructive Git commands nested in supported shell and command wrappers
+- Git arguments that contain a shell parameter. Only plain `$name` and
+  `${name}` expansions pass, and only inside plain double-quoted spans of
+  read-only subcommands (`status`, `log`, `diff`, `show`, and the other
+  inspection commands) that the guard parses directly, such as
+  `git log --format="$t %H"` or `git show "HEAD:$f"`, because only double
+  quoting prevents word-splitting into options. A parameter outside double
+  quotes (`$x`, `HEAD:$f`, `--format=$x`, `"a b"$x`) is denied because its
+  expansion can split into a write option such as `--output`. Every other
+  parameter form (`${=x}`, `${(z)x}`, `${x:-y}`, `$x[@]`, `$1`, `$@`, `$*`,
+  `$#`, and the unbraced zsh flags `$=x`, `$~x`, `$^x`, `$+x`) is denied even
+  inside double quotes, because it can expand to more than one word; a
+  backslash-escaped marker (`"\$t"`) is likewise denied, because the shell
+  executes the literal text while the argument still shows the bare marker.
+  The same four zsh flags are denied in a `git -C` directory. A literal `$`
+  that starts no expansion (a regex anchor such as `--grep='fix$'`) passes.
+  A `-c`/`--config` key whose value git executes as a program —
+  `core.fsmonitor`, editors and pagers, `core.sshCommand`,
+  `core.askPass`, `filter.*` clean/smudge/process, `diff.*`
+  textconv/external/command, `merge.*` drivers, `core.gitProxy`,
+  `interactive.diffFilter`,
+  `remote.*` uploadpack/receivepack, `gpg.program` and `gpg.*.program`, `credential.helper` and
+  `credential.*.helper`, each `pager.<cmd>` key — is denied with a literal
+  value as with a parameter, because git runs it during an otherwise
+  read-only subcommand. A disabling form of such a key passes: the bare key,
+  an empty value, or `false`. A `--config-env` form is always denied, because
+  its value comes from the environment. A key through which git loads code —
+  `core.hooksPath`, `include.path`, `includeIf.*.path`, `url.*.insteadOf`,
+  `url.*.pushInsteadOf` — is denied with each value. `git config` is denied
+  when it sets one of these keys; to read or unset the key stays allowed.
+  A redirection at the end of a read (`git config <key> 2>/dev/null`) is not
+  a value. A separate digit before a redirection (`5 >/dev/null`), a word of two
+  or more digits (`12>/dev/null`) and a quoted operator are values, so they
+  make a set.
+  Each `git config` argument must be a plain literal word, bare or in one
+  pair of quotes: a backslash, mixed quotes, an unquoted glob (`*`, `?`, `[`),
+  an unquoted brace list or range (`{a,b}`, `{1..3}`) or a line continuation
+  in the word or one that joins it to the next word is denied, because the shell can make a different
+  argument list from it.
+  An unquoted word that starts with `#` among the `git config` arguments
+  is denied, because the shell reads it and the words after it as a comment.
+  The git subcommand word must be a plain literal word in each git command:
+  `git {config,...}` and a subcommand split by a line continuation are denied.
+  A program that runs the command in its arguments (`nice`, `nohup`,
+  `timeout`, `sudo`, `watch`, `time`, `env`, `stdbuf`, `setsid`) is
+  unwrapped: the guard skips the options of the program and checks the
+  command that it runs, so `nice git -c core.fsmonitor=/abs/h.sh status` is
+  denied by the git rule and `sudo apt install git` passes. A runner
+  option that writes, edits or enters a file or directory by itself is
+  denied (`time -o`, `sudo -e`, `sudo -D`, `sudo -R`, `watch -s`). The
+  `timeout` duration and the `watch` interval must be literal numbers, and
+  each runner option word must be a literal word; only a separate option
+  value can be a parameter in double quotes (`sudo -u "$USER" ls`). A short
+  option word is read as getopt reads it, so the attached value in
+  `sudo -upostgres psql` is not taken as more options. With an archive working directory a command runner is not
+  unwrapped and is denied as an unknown program. Other command
+  runners (`doas`, `ionice`, `noglob`) are not unwrapped, and `watch` with
+  the command in one quoted word is not checked.
+  Each git global option word, and the value word of `-c`, `-C`,
+  `--git-dir`, `--work-tree`, `--namespace` and `--config-env`, must resolve
+  to one word: a backslash, an unquoted glob or an unquoted brace list or
+  range in it is denied (`git -c {core.fsmonitor=/abs/h.sh,status}`,
+  `git -{p,c} core.fsmonitor=/abs/h.sh status`). A parameter in such a value
+  is denied also when no subcommand follows (`git -c $x`). Plain quoted parts
+  pass (`git -c user.name='A B' log`).
+  `git config` section renames and removals (`--rename-section`,
+  `--remove-section`) and `--edit` are denied, because a rename can move a
+  key into an executed section and `--edit` starts an editor.
+  Command substitution output, a parameter that starts an
+  argument, and a parameter in the value of an option that git writes to or
+  runs as a command (`--output`, `--upload-pack`, `--receive-pack`, `--exec`,
+  `-c`, `--config-env`, or a `<transport>::<address>` remote) are denied in
+  every form. These option names match by prefix (`--upload-pa`, `--exe`),
+  because git accepts abbreviated long options; in archive context the same
+  prefix match applies to `--output`, `--ext-diff`, and `--textconv`. The
+  exact read-only option `--text` is not an abbreviation and stays allowed. Any
+  other quoting construct in the command (`$'...'`, `$"..."`, quotes inside `${...}`, quotes or
+  backslashes in a comment, here-documents and here-strings) disables the
+  exception, so every parameter in a git argument of that command is denied.
+  The exception applies only to commands the guard parses directly, never
+  inside wrapped shell strings (`eval`, `bash -c`, `sh -c`, PowerShell or
+  `cmd` command strings), where the outer shell expands the parameter first
 - archive glob/brace expansions and execution-capable read options such as
   `rg --pre`
 - direct write, edit, and patch tool calls targeting `.project/STATE.md`,
@@ -265,9 +409,12 @@ writes nor verifies that wiring. To add it yourself, register
 | Antigravity | `.agents/hooks.json` `PreToolUse` | [Antigravity hooks](https://antigravity.google/docs/hooks) |
 | OpenCode | JS plugin `tool.execute.before` | [OpenCode plugins](https://opencode.ai/docs/plugins/) |
 | Zed | no hook API — git hooks only | — |
+| Muse Code | no GSD Path hook integration — git hooks only | — |
 
-**Caveats:** The hook cannot prove which skill initiated a shell command or a
-build-phase edit, so AGENTS.md owns those re-entry cases. Grok and Kimi
+**Caveats:** The hook cannot prove which skill initiated a build-phase edit
+when the routed build phase is already active. Shell product writes use the
+same phase gate as file-edit tools; AGENTS.md still owns plain-prompt re-entry
+when no `.project/STATE.md` exists. Grok and Kimi
 fail-open on hook errors by design. Copilot, Kimi, Kiro, and Antigravity may
 not intercept subagent tools — treat coverage as orchestrator-level.
 
@@ -279,6 +426,7 @@ not intercept subagent tools — treat coverage as orchestrator-level.
 | `ship:` commit blocked with `app.py` staged | Ship commits may only touch `.project/` |
 | Tool denied editing archive | Pre-tool guard — use active paths, not archive |
 | Hook not running in Cursor | Run `--hooks-refresh-full --cursor --project /path/to/repo` |
+| Installer stops with `cannot chain` | See [existing Git hooks](#existing-git-hooks): rename your hook to `<hook>.gsd-path-chained`, or remove the stale chained file, then rerun |
 | `--hooks-refresh` rejects an unmanaged guard | Move the foreign guard aside, then rerun refresh; use `--hooks-init` if guards are wanted |
 | Runtime missing, invalid, or legacy | Follow [runtime restoration or migration](DOCS.md#project-runtime-versions) |
 

package/MIGRATE.md

@@ -10,6 +10,18 @@ selected project. Core history stays in `.planning/`; Path creates its own
 `.project/` state through the normal router. Core phase positions and completed
 plans do not become passed Path gates.
 
+## Requirements
+
+- The default branch of `origin` can have any name, for example `master`.
+  Path initialization records it in `.project/STATE.md` as `default_branch`
+  and ships onto it. Run `git remote set-head origin --auto` before the first
+  Path run: an unset `origin/HEAD` records `main`. See
+  [default branch](WORKFLOW.md#default-branch).
+- Pull-request shipping supports GitHub.com only. On GitLab, Gitea, or GitHub
+  Enterprise Server, ship with `direct`, or with
+  [`external-landing`](WORKFLOW.md#integration) when the default branch
+  accepts merge requests only.
+
 ## Start
 
 Install or update GSD Path using [the install guide](QUICK.md). In the Core

package/QUICK.md

@@ -13,8 +13,10 @@
 One router skill drives a gated pipeline: inspect → define → research → decide →
 plan → build → ship. Every handoff lives in `.project/` so any session can resume from disk.
 
-**Hosts:** Codex, Claude Code, Grok, OpenCode, Copilot CLI, Qwen, Antigravity,
-Cursor, Zed, Kiro, Kimi Code.
+**Hosts:** Codex, Claude Code, Grok, OpenCode, Antigravity, Cursor, and Kimi
+Code have a passing live milestone for release 1.6.0. Copilot CLI, Qwen, Zed,
+Kiro, and Muse Code install, but have no live milestone for that release. See
+[host tiers](README.md).
 
 ---