@opengsd/gsd-path 1.3.1 → 1.5.0

package/CHANGELOG.md

@@ -3,98 +3,360 @@
 All notable changes to [@opengsd/gsd-path](https://www.npmjs.com/package/@opengsd/gsd-path)
 are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
-## [1.1.0] - 2026-09-18
+This file covers the npm package: the skills, the installer, the pipeline
+scripts and project runtime, the guard hooks, and their documentation. Until
+1.4.0 it also lists changes to the monitor daemon and its dashboard, which are
+in this repository but not in the npm package. From October 2026 the desktop
+app and the daemon have their own file,
+[daemon/app/CHANGELOG.md](daemon/app/CHANGELOG.md). Release bookkeeping and
+test-only changes are not listed; the Git history has them.
+
+## [1.5.0] - 2026-10-09
 
 ### Added
-- Scoped npm package `@opengsd/gsd-path` with trusted publishing workflow
-- Release trust evidence validation and host matrix documentation
+- record runtime hotfix provenance on the declaration
+- add signed self-update
+- add the Skills, Stats, Settings, and Environment pages and the setup wizard
+- register the hosts, project operation, and env routes
+- add project setup operations for the app
+- detect installed coding agents
+- add the env file module for the app's Environment page
+- add the stats route for the app's charts
+- add the project board, project page, and tray popover
+- add the Tauri shell and React setup screens
+- add settings and diagnostics routes
+- install skills from the verified npm release
+- report requirements in the launch check
+- add the launch check for the native app
+- add --require-token to gate POST routes
+- add external-landing mode for forge-neutral ship
+- add Muse Code as a shared-agents host
+- rule on edges and prohibitions at define, gate held-out checks at plan and final
 
 ### Changed
-- Release workflow and maintainer documentation for npm publication
-
-## [1.0.0] - 2026-09-15
+- prepare 1.5.0 minor candidate
+- point trust evidence link to current receipts
+- refresh all seven host release receipts
+- Name interactive.diffFilter in HOOKS.md executed-key list
+- align guard, worktree pin, provenance, planner docs
+- sync generated skill resource copies
+- describe daemon hook-op migration and default hosts
+- app: migrate a legacy runtime in the same click as a hook action
+- app: send a legacy runtime to the update, not a hook refresh
+- say macOS app builds are signed and notarized
+- app: prepare 0.1.1, the first signed macOS build
+- prove signing setup keeps keychain on success
+- app: delete signing keychain on setup failure
+- remove stale unsigned-build text after macOS signing
+- app: sign and notarize macOS builds in the release workflow
+- make diagnostic command assertion platform independent
+- clarify patch finding source fields (#326)
+- require maintainer rewrite of drafted changelog entry
+- strengthen alias update regression assertions
+- assert router alias payload refreshes on update
+- rewrite the changelog entries for readers
+- list the release upload script test in RELEASE.md
+- prove the release upload script on macOS, Windows, and Linux runners
+- Sync generated skill resource copies
+- cover dispatch brief bases and in-flight lint regressions
+- describe the desktop app in the README and add its changelog
+- Document round exit-receipt reread in RUNTIME.md
+- Merge validated main integration while preserving PR history
+- Update ADR 0004 for Windows pinned-handle evidence reads
+- sync detect_project skill copies
+- correct app update check and release facts
+- point README page list at route.ts
+- Fix daemon README same-origin list and hosts docstring
+- add app workflows to the RELEASE.md CI table
+- Merge remote-tracking branch 'origin/main' into HEAD
+- build tester installers on app-v tags and run shell tests
+- Revert "fix: treat empty .project directory trees as greenfield (#273) (#292)"
+- Revert "fix: reject Verify commands the host guard would refuse at plan time (#302)"
+- Revert "fix(guard): allow read-only closed-milestone shell between ship and bind-next (#301)"
+- match only real pip commands in the launch tests
+- document INTENT SC heading text for multi-line criteria (#279) (#303)
+- align plugin source wording with npm release source
+- Document daemon version and pid in /status
+- record native app design handoff and React frontend ruling
+- run pinned-runtime reload in subprocess to avoid import pollution
+- merge main: integrate #254/#265 and keep pinned-runtime test cleanup
+- sync skill copies for state_checkpoint landed base fix
+- sync skill copies for landed member base fix
+- double-restore bundled scripts after pinned-runtime test
+- drop pinned-runtime tests from native-attempt PR (#209 owns them)
+- Revert "test: restore bundled scripts after pinned-runtime reload test"
+- restore bundled scripts after pinned-runtime reload test
+- invoke pipeline_state CLI from bundled script path
+- retrigger checks
+- sync skill copies after isolation change
+- revert: keep ca89 dispatch finish path that passes member round tests
+- merge main
+- platform-neutral PowerShell path quoting expectation
+- sync worktree_paths skill copies
+- align package verify graph with main (drop stray check:locks)
+- sync state_checkpoint skill copies
+- expect LF-normalized intent hash for CRLF on-disk files
+- skip WSL drvfs mount probes on Windows CI
+- merge main into cursor/fix-spec-reach-probes-f72c
+- merge main and sync skill resources
+- merge main into cursor/fix-git-worktree-legacy-f72c
+- merge main into cursor/fix-task-briefs-plan-deps-f72c
+- merge main into cursor/fix-windows-member-lock-run-shell-f72c
+- patch os.path.normcase in Windows session path test
+- fix Windows normcase test on Linux CI (create=True, patch sep)
+- sync detect_project copies after listdir_anchored fix
+- update release notes for v1.4.0
+- Point local shard command at py.mjs wrapper
+- shard the Windows Python suite
 
-### Added
-- Initial public release of the disk-backed GSD Path pipeline
-- Multi-host installer, skills package, and project contracts
+### Fixed
+- parse research questions with backticks
+- Fix package-level dispatch resource defaults
+- deny git -c keys whose value git executes
+- close zsh flag and escaped-marker gaps in the git parameter exception
+- review findings on the 353 branch
+- dispatch footguns from the 1.4.0 multi-repo field report
+- dashboard probe resolves the pinned runtime via the project launcher
+- guard hook precision for read-only commands
+- allow same-wave file overlap between dependency-ordered tasks
+- members validate and repair stop rejecting the refs Path creates
+- lint landed member briefs at their member base
+- ignore stale retired bind-next journals
+- recover blocked serial tasks and retire unused verify sidecars
+- preserve code spans in archive validation (#328)
+- allow proven safe shell guard commands
+- tolerate bytecode caches in pinned runtimes
+- validate superseded wave review cycles together
+- prioritize repair waves after blocked review (#315)
+- accept prepared archive ship log events
+- exclude Python bytecode from npm releases
+- stabilize docs audit numbering (#299)
+- allow research questions across multiple dimensions
+- fix installer ownership of prerelease aliases
+- fix installer recognition of suffixed versions
+- Fix dispatch task brief validation bases
+- find release files without globstar in the app release workflow
+- reread task exit receipt before marking orphaned
+- verify Windows pins and drain refused POST bodies
+- list Windows evidence dirs by path while opens stay handle-relative
+- anchor detect_project evidence reads on pinned handles
+- remove the host guard Verify check that PR #305 carried from #302
+- reject Verify commands the host guard would refuse at plan time (#302)
+- tolerate missing lower milestone archives (#269) (#306)
+- treat superseded wave review cycles as history (#274, #278) (#305)
+- allow plan intent corrections to return to define (#304)
+- allow read-only closed-milestone shell between ship and bind-next (#301)
+- Fix final-review HEAD checks to allow runtime-pin commits (#297)
+- require wave evidence line in quick-lane final scope template (#296)
+- tighten task brief path token detection (#281) (#295)
+- Fix multiline review bullet field parsing for final gate and archive (#294)
+- Fix Surfaces parsing to split only on top-level commas (#293)
+- treat empty .project directory trees as greenfield (#273) (#292)
+- isolate pinned-runtime in-process test and reload order
+- parse frontmatter # only as YAML comment (#268) (#289)
+- keep the pinned-runtime reload test out of suite discovery
+- landed member base resolution and missing STATE.md dispatch records
+- resolve landed member base on coordinator or member repo
+- allow dispatch records when STATE.md is absent
+- validate landed member task base in member repo
+- do not refresh native shell when prior attempt is blocked
+- restore finish_task landing flow while keeping native shell refresh
+- validate landed member task bases on coordinator
+- member finish verify logging and force sidecar retirement
+- allow force member sidecar retirement without task-file rejection gate
+- pass task-file when force-retiring member sidecars
+- record member verify on coordinator task and force-retire sidecar
+- resolve landed member bases on coordinator and finish native member dispatches cleanly
+- refresh native dispatch shells on re-activation and prefer live task state at finish
+- exclude check_lock_usage from LK_LOCK self-scan
+- reject Windows symlinks and junctions in handle-based reads
+- lazy pipeline_git import with git fallback for skill bundles
+- prefer isolation import before scripts package
+- treat native shells as pre-spawn, not orphaned
+- phase-gate shell writes only on bound milestone branch in-tree
+- Windows parity for file reads, subprocess, tray, and install
+- record native activations for attempt limits
+- WSL drvfs index.lock workaround for state commits
+- phase-gate shell writes to product files
+- load pinned runtime helpers in dispatch_driver
+- ignore same-wave overlap between landed tasks
+- normalize CRLF in user-edited pipeline text
+- prefer scripts.isolation when scripts/ is on sys.path
+- worktree list without -z and posix show paths
+- allow optional git trailers after ship commit body
+- align gate-plan task brief check with approval checkpoint
+- allow path_config model-policy.json at approval
+- list .project through fresh directory fd on Linux
+- member landing lock and spec command timeout drain
+- copy staged skill entries into reserved directory
 
-## [1.2.0] - 2026-09-20
+### Other
+- fix install command receipts and 1.4.0 trust evidence
+- deny pager.<cmd> config keys that git executes
+- parse runner short options as getopt, deny non-literal option words
+- deny file-valued runner options and non-literal runner operands
+- unwrap command runners so git checks reach payload
+- scope git wrapper denial to exec-prefix programs
+- deny git behind programs the guard does not model
+- deny unresolved git option words and credential helpers
+- deny joined continuations and expanding git option values
+- require literal git subcommand, deny comments in git config
+- deny non-literal git config arguments
+- treat only one ASCII digit as redirection file descriptor
+- allow redirected git config reads, keep digit sets denied
+- deny gpg program keys and redirected git config sets
+- parse git config modes; .git/config append stays open
+- close executed git config keys, persisted form, disabling values
+- narrow zsh flag detector and cover git -C paths
+- keep exact --text allowed under git option prefix rule
+- match denied git options by abbreviated prefix
+- deny parameters in command-valued git options
+- accept only plain name expansions in git parameter exception
+- deny git parameters inside wrapped shell strings
+- fail closed on unrecognized quoting in git parameter exception
+- allow git parameters only inside double-quoted spans
+- deny bare and substituted parameters in read-only git arguments
+- fix guard fail-opens and remaining 353 review findings
+- app: Add guards uses installed agents when no hosts sent
+- narrow macOS signing claim to Privacy & Security approval
+- Correct unsupported Fixed and Security changelog entries
+- assert incomplete builds upload nothing at all
+- Insert new changelog entries above existing entries
+- Restore Windows start step in manual monitor README section
+- Classify directory SKILL.md marker as unverified on Windows
+- Reject symlinked SKILL.md marker in Windows bundle probe
+- Detect junctions at held Windows handles; stat-only file opens
+- stop daemon before install, add .deb update, tray dialog
+- Cause: GitGuardian reported one "Generic High Entropy Secret" in commit be3bd5d4, file daemon/app/src/mocks/environment.ts line 10. The value was `tsk_mock_8f3a91c2d7`, a made-up key for TYPESAFE_API_KEY in the dev-only browser mock. It is not a real credential, so nothing needs rotation. Fix: replaced the value with the plain placeholder `mock-api-key` (one line). No other file uses the old value. No test added: this is mock data, not logic. Verification: `tsc --noEmit` is clean and Vitest passes (14 files, 226 tests). GitGuardian was not run locally, so the check result is not confirmed. Remaining risk: GitGuardian scans each commit of the PR, and commit be3bd5d4 still contains the old string. The check can stay red after this commit. If it does, the owner has two options: mark incident 37796517 as a false positive / test credential in the GitGuardian dashboard, or rewrite the branch history to drop the string from be3bd5d4. I did neither: the dashboard needs the owner's account, and a history rewrite plus push is outside this phase
+- compare with release in use, share plugin state
+- unify update rules, badge count, and env switch
+- Fix hooks-init host flags and member hook state
+- Fix env quoted values, host commands, None phase
+- Remove command line from port owner detail
+- Report program name, pass PATH to children, handle Reopen
+- Serialize boot, refresh PATH, fix port screen and autostart
+- The fix is in place, but the Windows failure is not reproduced locally (macOS); only CI on Windows can confirm it. - **Cause:** `test_foreign_host_refused` got `WinError 10053` on `/api/config/parents`. `do_POST` in `daemon/gsd_daemon/serve.py` sent a refusal (403 or 415) without reading the request body. On Windows, a socket closed with unread data resets the connection, so the client can lose the reply. This is a timing race, which is why only one shard and one route failed. - **Origin:** the same-origin refusal is already on main, so the race is not new in this PR. The token refusal that this PR adds has the same exposure. - **Fix:** `do_POST` now reads the full body (per `Content-Length`) before any reply and gives it to the route handlers through `self.rfile`. It is one change at the top of `do_POST`, plus `import io`. It covers all refusals, the 404, and `/api/refresh`. The check order (origin 403, content type 415, token 403) and the route handlers are unchanged. - **Behavior change:** a negative `Content-Length` is now read as 0. Before, the server waited on the socket. - **Verification:** `python3 -m unittest tests.test_daemon_serve` ran 32 tests, all OK. I added no test, because the existing `PostOriginTests` is the test that fails on Windows. - **Not done:** the ponytail and test-writer skills were not run as separate steps, and the change is not committed; it is one modified file in the worktree
+- Keep unknown config keys, wake poll, mask log credentials
+- Apply settings under scan lock; skip session scan in request
+- Harden daemon settings routes: atomic save, host check, finite prices
+- compare updates with release in use; refuse git-source selection
+- fail loud on unpublished pin; reject prerelease selection
+- Two test defects from this PR are fixed in tests/test_daemon_launch.py. No product code changed. The other failures are not from this change. Caused by this PR (fixed): 1. daemon, verify (18), verify (20): test_other_service_on_port_blocks_without_install failed on Linux. The assertion `runner.ran("pip") == []` matches by substring, so it caught the Linux-only python-venv check `python -c "import ensurepip"`. The assertion now checks that no `python -m venv` command ran, which is the first step of an install. 2. windows (3.9 and 3.12, shard 0): three LegacyAutostartTests run with platform="darwin" and reach `os.getuid()`, which does not exist on Windows. They now skip when `os.getuid` is absent, the same rule tests/test_daemon_install.py uses. Not caused by this PR (no change): - windows (3.9 and 3.12, shard 3): the 3.12 log shows only two test_member_tasks errors; I did not read the 3.9 log. - verify (18): the other 43 errors are in test_member_*, test_pipeline_*, test_workflow_architecture, test_trust_evidence and one test_rebase_recovery test. I did not read the verify (20) log beyond the excerpt. - The intent names all of these suites except test_rebase_recovery as the main-branch pollution from PR #260. These checks stay red until that separate fix lands. Verification: - RED: the CI log shows the Linux failure (`['.../python3', '-c', 'import ensurepip']] != []`) and the Windows AttributeError on `os.getuid`. - GREEN: `python3 -m unittest discover -s tests -p test_daemon_launch.py` ran 30 tests, OK (macOS). The changed test also passes with the installer platform forced to linux. With `os.getuid` removed, LegacyAutostartTests ran 6 tests, OK, 3 skipped. - Sabotage: with the port problem made non-blocking, the changed test fails. - Not run locally: the tests on real Linux or Windows, and the full suite
+- Make the temporary daemon build copy user-writable
+- Report failed legacy cleanup as non-blocking; check venv pip
+- Harden launch check requirements and error reporting
+- record env route flag rule and browser transport
+- record read-only browser and token-gated env rulings
+## [1.4.0] - 2026-09-30
 
 ### Added
-- add Path settings and project history dashboard
-- add optional Jev evidence screening
-- store worktrees and pinned runtimes outside project checkouts
-- centralize sub-agent model selection policy
+- **Multi-repo milestones.** One coordinator project can plan, build, review,
+  and ship tasks in other repositories (members). A task names its repository
+  with `repo:`. Each member gets a marker, guard hooks
+  (`--member-of`), a Path-owned checkout for its tasks, and a bound branch at
+  build start. Landings in two repositories are journaled so an interrupted
+  one can be finished. Members integrate by direct merge or pull request, and
+  a member landing can be undone. A member accepts a push only with an
+  authorization for that ref, and refuses symlinked lock, marker, and task
+  copy paths.
+- **Native Windows support.** The installer, hooks, state locking, dispatch,
+  Verify commands, and the project runtime run on Windows with Git for
+  Windows (Git Bash). A Windows job in CI now blocks a merge.
+- **Managed `AGENTS.md` block.** The installer adds a marked Path block to an
+  existing `AGENTS.md` and keeps the owner's text, on update and on uninstall.
+  The block is smaller; phase rules moved into the skills.
+- **Pre-approved gates.** `--pre-approve intent,plan` grants the intent and
+  plan approvals for one milestone, for unattended quick-lane runs (#150).
+  Ship approval stays manual.
+- **Native retry.** A failed task that was dispatched natively can be retried
+  and finished, also for a member task.
 
 ### Changed
-- Correct stale release guidance and consolidate scope references
-- record passing eight-host release gate
-- validate corrected OpenCode release evidence
-- validate recovered Claude release evidence
-- record affected release gate results
-- preserve blocked host evaluations without receipt fallback
-- record passing Antigravity Kimi and Grok release runs
-- record remaining 1.2.0 release gate failures
-- record Kimi receipt and complete offline recheck
-- preserve 1.2.0 host receipts and release blockers
-- record v1.3.0 live release evidence and blockers
-- bump version to v1.3.0
-- Align release documentation with risk-based host validation
-- bump version to v1.2.0
-- Automate npm release docs, pack verification, and provenance (#133)
-- refresh README changes and dashboard screenshots
-- Refresh dashboard navigation and file history documentation
-- Clarify Jev receipt fields and consolidate documentation
-- Refresh dashboard update and guard documentation
-- Correct runtime installation, update, guard, and uninstall documentation
-- Correct model policy and dispatch documentation
+- The verify ledger records the repository of each row, and a build stops when
+  a member repository changed outside Path.
+- The monitor daemon refuses POST requests from other websites and requests
+  that are not JSON.
+- The dashboard and the tray show the project folder beside the worktree and
+  wrap long paths.
 
 ### Fixed
-- reuse unchanged host receipts for releases
-- verify prepared releases without advancing failed versions
-- scope release evidence to affected hosts
-- show project runtime updates and release completed milestone guards
+- An ignored `.DS_Store` inside `.project` no longer blocks setup, landings, or
+  the ship check (#149).
+- A landing is refused when ignore rules hide `.project` state (#145).
+- `finish` lands parallel tasks that were dispatched natively (#142).
+- `retire` recovers a task worktree that was only half retired (#143).
+- Empty host `.claude` folders are removed before `.project` gates (#144).
+- The docs audit keeps `Repo root` on the primary repository (#148).
+- A build checkpoint commits a verify ledger that old ignore rules hid (#158).
+- The decide phase can run the research handoff check.
+- The installer names a working path when `--project` finds an existing
+  contract.
+- The update notice says that local edits to skills are not carried forward
+  (#151).
 
-### Other
-- Fixed tests/package.test.mjs to invoke git_guard.py with pre-commit in a temporary Git repository instead of unsupported --help. The focused test failed before the fix and during restored-original sabotage. All 6 package tests now pass; resource sync and diff checks pass. Verified locally on Node 26; Node 18/20 CI reruns remain with the outer executor
-- Preserve historical commit selection across relative document links
-- Validate Jev probability normalization with CLI regression coverage
-- Record passing focused checks and isolation violation
-- Fix integration guard and runtime installer regression coverage
-- Fixed stale runtime paths in tests/test_git_guard.py using the installed runtime resolver. Both CI failures reproduced before the fix; all 38 Git guard tests now pass. Both corrected tests also caught a temporarily disabled native guard, which was restored. git diff --check passed. Only the test file changed; remote CI remains for the outer executor
-- Fix pinned runtime routing, guard blocking, and launcher bytes
-- Restore same-cycle recovery after partial review completion
-- Isolate assignment rejections and align native panel exclusions
-- Fix dispatch isolation, legacy pinning, and independent panel selection
+### Security
+- Guard bypasses through Git Bash paths and directory junctions on Windows are
+  closed.
+
+## [1.3.1] - 2026-09-22
+
+### Changed
+- Clearer guidance for the legacy runtime migration and its backup.
+
+### Fixed
+- The legacy runtime migration keeps older runtime folders that Git does not
+  track, and the installer help describes this case.
 
 ## [1.3.0] - 2026-09-21
 
 ### Added
-- migrate legacy runtimes during upgrades
+- An upgrade moves a legacy in-repository runtime out of the project and
+  leaves a backup to review (`--runtime-migrate`).
 
 ### Changed
-- Clarify receipt reuse and consolidate release policy guidance
-- Clarify legacy upgrade guidance and verify syntax
-- update release notes for v1.2.0
+- On Cursor and Copilot, only the reviewer corrects a review, and only while
+  its review cycle is open. A closed review cycle is not rewritten.
+
+## [1.2.0] - 2026-09-20
+
+### Added
+- **Path settings.** Set the shipping mode, the review panel, and the model and
+  effort per role, for the user or for one project, in the dashboard or with
+  `path_config.py`.
+- **Project history in the dashboard.** Browse project files and archived
+  milestones, read a file at any Git commit, and load the full recorded
+  evidence.
+- **Optional Jev evidence screening.** Reviewers can ask for an advisory check
+  of chosen criteria and evidence. It is off by default and never replaces a
+  recorded review or Verify.
+- **External worktrees and pinned runtimes.** Task, verification, and
+  integration worktrees live outside the project checkout. A project pins its
+  runtime version by content digest, with upgrade and restore commands.
+- **One model policy.** User, project, host, and task choices for sub-agent
+  models go through one resolver. A recorded assignment stays pinned.
+
+### Changed
+- npm releases are automated: release notes, package verification, and
+  provenance.
+- The release gate validates only the hosts a change affects and reuses
+  unchanged host receipts.
 
 ### Fixed
-- validate installer changes without live host reruns
-- preserve closed review cycles in host recovery
-- clarify owner gates and accept serial task release evidence
+- The dashboard shows project runtime updates and their results.
+- After verified integration, ordinary branches can take product work again
+  while archived milestones stay protected.
 
-### Other
-- Clarify reviewer ownership; live verification remains pending
-- Reject unretired verification worktrees and branches in release evidence
+## [1.1.0] - 2026-09-18
 
-## [1.3.1] - 2026-09-22
+### Added
+- Scoped npm package `@opengsd/gsd-path` with trusted publishing.
+- Release trust evidence validation and the host matrix.
 
 ### Changed
-- Clarify legacy runtime backup guidance
-- Consolidate legacy runtime migration guidance
-- prepare 1.3.1 patch candidate
-- Clarify legacy runtime migration documentation
-- update release notes for v1.3.0
+- Release workflow and maintainer documentation for npm publication.
 
-### Fixed
-- describe untracked legacy migration in help
-- preserve older untracked runtimes during migration
+## [1.0.0] - 2026-09-15
+
+### Added
+- First public release of the disk-backed GSD Path pipeline.
+- Multi-host installer, skills package, and project contracts.

package/DOCS.md

@@ -35,6 +35,7 @@ DOCS.md (here)     four journeys in one place
 | **Upgrading** — new gsd-path version | [UPDATE.md](UPDATE.md) |
 | **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) |
 
 ---
 
@@ -92,7 +93,8 @@ node scripts/install.mjs --claude --project "$(pwd)" --hooks
 ```
 
 **Requirements:** Node 18.17+. Project installs also require Python 3.9+ as
-`python3` or `python`. **Always** restart the agent session after install.
+`python3`, `python`, or `py -3`. Windows also needs Git for Windows (see the
+README's Windows notes). **Always** restart the agent session after install.
 
 **Host flags** are derived from `scripts/skill-resources.json`. Run
 `node scripts/install.mjs --help` for the current `--<host>` list.
@@ -157,6 +159,9 @@ state or bypasses a gate.
 
 ### Gates (what you approve)
 
+These are the usual checkpoints. For the opt-in quick-lane grant, see
+[pre-approval in the README](README.md#start-your-first-project).
+
 | Phase | You do |
 | --- | --- |
 | Define | Answer gaps or review milestone derivation; approve intent playback |
@@ -242,8 +247,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.
@@ -300,7 +307,8 @@ Full tree: [README.md](README.md#handoff-contract).
 | Project-local skills | `node scripts/install.mjs --update --local` |
 | From npm | `npx @opengsd/gsd-path@latest --update` |
 | Guard scripts | `node scripts/install.mjs --hooks-refresh --project PATH` |
-| `AGENTS.md` / `WORKFLOW.md` | Manual merge — installer refuses overwrite |
+| `AGENTS.md` | `node scripts/install.mjs --update --project PATH` — replaces only the GSD Path block |
+| `WORKFLOW.md` | Manual merge — installer refuses overwrite |
 | Health check | `node scripts/install.mjs --doctor [--project PATH]` — read-only; flags missing/stale skills, hook drift, and bad pipeline state |
 
 Full guide: **[UPDATE.md](UPDATE.md)**. Router may print a one-line npm update notice.
@@ -321,10 +329,8 @@ Restart the host session. Confirm with `ls ~/.claude/skills/gsd-path` (or your h
 Yes: `node scripts/install.mjs --cursor` (add other flags as needed).
 
 **Will install overwrite my `AGENTS.md`?**
-No — if managed project files already exist, a plain install refuses and installs
-nothing for that project. Use `--update --project PATH` to refresh skills and the
-managed `.gsd-path/` runtime while keeping your contracts; merge project
-contract updates manually ([UPDATE.md](UPDATE.md)).
+No. GSD Path adds one marked block and keeps your text outside it byte for
+byte. See [Update project contracts](UPDATE.md#update-project-contracts).
 
 **Where is pipeline state?**
 `.project/` in your repo — not chat history.
@@ -357,7 +363,9 @@ document with a body is brownfield and routes to inspect. A title-only README,
 GSD Path skill bundles: a `gsd-path*` or `ogsd*` bundle is verified under a
 supported installer skill root or when it contains `SKILL.md`; a similarly
 named source directory still counts normally. Those scaffold-only trees stay
-greenfield and route to define. Other `.project/` content without STATE.md is
+greenfield and route to define. An ignored, untracked regular `.DS_Store`
+directly in `.project/` does not block setup, even if it appears while
+STATE.md is being created. Other `.project/` content without STATE.md is
 orphaned and blocks for recovery. An owned state, including the new-GitHub
 bootstrap state, routes by STATE.md after classification without running the
 initializer. After a milestone ships, the next one inspects again.
@@ -391,6 +399,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

@@ -31,8 +31,10 @@ writes a fixed artifact under `.project/`; the next phase reads only from disk.
 You can close your session at any point and a fresh session resumes exactly
 where you left off.
 
-You are the gate: nothing advances past intent, plan approval, or final review
-without your approval.
+You approve intent, plan, and final shipping. For an unattended quick-lane run,
+you can grant intent and plan approval when invoking the router; see
+[pre-approval in the README](README.md#start-your-first-project). Final shipping
+still needs your approval.
 
 ### The pipeline
 
@@ -79,7 +81,10 @@ Use the [router and phase invocation table](README.md#install-summary) for your
 ### Requirements
 
 - **Node 18.17+** for `scripts/install.mjs` (recommended; also the npm `gsd-path` bin)
-- **Python 3.9+** required for project installs, project refresh, and project-state
+- **Windows:** runs natively (no WSL). Needs Git for Windows, whose Git Bash runs
+  git hooks and task Verify commands, and long paths enabled for deep worktrees.
+- **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
@@ -101,7 +106,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/` |
@@ -171,7 +176,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.
@@ -427,6 +432,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 |
 
@@ -442,6 +448,7 @@ layers. Every child brief names absolute input/output paths and bounded scope.
 | Skills missing after install | Restart host session; [UPDATE.md](UPDATE.md) |
 | Router blocked on branch | Check out `STATE.branch` or follow router instructions |
 | Phase says precondition missing | Run the producing phase it names |
+| Task landing or Verify reports ignored `.project/` state | Fix the matching product ignore rule through an owning task or patch wave (for example, anchor `build/` as `/build/`), then resume the pipeline. For the pre-existing ignored verify ledger exception, see the [build checkpoint](skills/gsd-path-build/SKILL.md). |
 | Pipeline on unrelated work | Explicit invocation only — [DOCS.md](DOCS.md#faq) |
 | Contradictory STATE / tasks | Re-invoke router; artifacts outrank chat |
 | Archive tamper blocked | Expected with hooks — [HOOKS.md](HOOKS.md) |

package/GUIDE.md

@@ -11,7 +11,7 @@ DOCS.md     hub — install, use, understand, update, FAQ
 └── README.md   reference tables, handoff contract, repo layout
 
 WORKFLOW.md   agent SOP (copied into your project with --project)
-AGENTS.md     operating rules (copied into your project)
+AGENTS.md     operating rules (marked block in your project; see UPDATE.md)
 ```
 
 | Doc | Read when |