@opengsd/gsd-path 1.3.0 → 1.4.0

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 |

package/HOOKS.md

@@ -42,7 +42,8 @@ node scripts/install.mjs --claude --project /path/to/repo --hooks
 ```
 
 For a project that already has `AGENTS.md` and `WORKFLOW.md`, initialize only
-the guards and keep those contracts unchanged:
+the guards and keep those contracts unchanged (use `--update --project` to
+refresh the `AGENTS.md` block):
 
 ```bash
 npx @opengsd/gsd-path --hooks-init --claude --project /path/to/repo
@@ -86,11 +87,13 @@ manual activation is complete, Codex's guaranteed manifest tier is `git-only`;
 changing the hook requires review again.
 
 **Windows / interpreter caveat:** hooks and native host settings invoke a
-Python interpreter that the installer probes at install time — `python3` first,
-then `python` (plain `python3` usually does not exist on Windows). If neither
-runs, hook installation stops before writing instead of pinning a missing
-interpreter. The `sh` hook scripts themselves need a POSIX shell (Git for
-Windows provides one).
+Python interpreter that the installer probes at install time: `python3` first,
+then `python`, then the `py -3` launcher (plain `python3` usually does not
+exist on Windows). If none runs, hook installation stops before writing
+instead of pinning a missing interpreter. The `sh` hook scripts themselves need
+a POSIX shell, which Git for Windows provides. Claude Code runs Windows hook
+commands in Git Bash, so wrapped Core hooks are bash-quoted and their original
+command runs through Git Bash, not cmd.exe.
 
 ### Updating after package upgrade
 

package/QUICK.md

@@ -22,7 +22,7 @@ Cursor, Zed, Kiro, Kimi Code.
 
 ```text
 [ ] 1. Install skills (step 1)
-[ ] 2. Install project rules in your repo (step 2) — skip if repo already has AGENTS.md
+[ ] 2. Install project rules in your repo (step 2) — an existing AGENTS.md keeps its text
 [ ] 3. Restart agent session
 [ ] 4. Open repo in agent; invoke router (step 3)
 [ ] 5. Approve gates as they appear (step 4)
@@ -105,6 +105,9 @@ Codex invokes it as `$gsd-path-discuss`.
 | Build | Escalations only |
 | Ship | Approve patch waves if blocked; approve archive and ship when green |
 
+For unattended quick-lane runs, see
+[pre-approval in the README](README.md#start-your-first-project).
+
 ---
 
 ## 5. Resume

package/README.md

@@ -16,14 +16,14 @@ Support means the installer and dispatch contract exist. See the
 proof and each host's guard tier.
 
 <!-- release-docs -->
-**Latest npm release:** [@opengsd/gsd-path@1.3.0](https://www.npmjs.com/package/@opengsd/gsd-path/v/1.3.0) — [release notes](CHANGELOG.md#130---2026-09-21)
+**Latest npm release:** [@opengsd/gsd-path@1.4.0](https://www.npmjs.com/package/@opengsd/gsd-path/v/1.4.0) — [release notes](CHANGELOG.md#140---2026-09-30)
 
 **Recent highlights**
-- migrate legacy runtimes during upgrades
-- validate installer changes without live host reruns
-- preserve closed review cycles in host recovery
-- clarify owner gates and accept serial task release evidence
-- Clarify receipt reuse and consolidate release policy guidance
+- key verify ledger rows by repo and fail closed on member drift (S3d)
+- guard coders in member sidecars with coordinator host hooks (S3c3b2)
+- dispatch and land member tasks in build rounds (S3c3b1)
+- activate member tasks with a live copy in the member sidecar (S3c3a)
+- prove landed member tasks from record and member landing (S3c2b)
 
 <!-- /release-docs -->
 
@@ -77,6 +77,21 @@ published release.
 Requires **Node.js 18.17+** for the npm installer and **Python 3.9+** for
 project contracts and pipeline helpers. Install and sign in to a supported
 coding-agent host separately; GSD Path installs its skills, not the host itself.
+
+**Windows** runs natively; WSL is not required. Install
+[Git for Windows](https://git-scm.com/download/win): git hooks and task Verify
+commands run in its Git Bash, never the System32 WSL launcher (`GSD_PATH_BASH`
+overrides the path). Install a real Python from python.org or
+`winget install Python.Python.3.12`; the Microsoft Store `python` alias stub
+does not count. The installer accepts `python3`, `python`, or the `py -3`
+launcher. For deep managed-worktree paths, turn on long paths
+(`git config --global core.longpaths true` and Windows' `LongPathsEnabled`);
+`--doctor` warns about both. Git for Windows defaults to
+`core.autocrlf=true`, so project installs add a managed
+`/.project/** text eol=lf` rule to the repository's local `.git/info/attributes`
+(never committed; delete the `# gsd-path:begin` block to remove it). That keeps
+pipeline state LF in every worktree while product files follow your setting.
+
 The public npm package is **[@opengsd/gsd-path](https://www.npmjs.com/package/@opengsd/gsd-path)**.
 
 ```bash
@@ -98,7 +113,9 @@ npx @opengsd/gsd-path@latest --update --project /path/to/your-repo
 Use host flags such as `--claude --codex` instead of `--all` to select hosts.
 For project-local skills, run from your project directory and add `--local`
 to install and update commands. `--project PATH` selects where contracts are
-written; it does not change the directory used by `--local`. Run
+written; it does not change the directory used by `--local`. If the repo
+already has an `AGENTS.md`, the install adds a marked GSD Path block and keeps
+your text; see [project contracts](UPDATE.md#update-project-contracts). Run
 `npx @opengsd/gsd-path@latest --help` for all options. After installing, invoke
 `$path` in Codex or `/path` on slash-command hosts to start the pipeline.
 See [Install (summary)](#install-summary) for the host list and source-checkout commands.
@@ -116,6 +133,12 @@ contain newer changes.
 4. Resume later from the same folder with the router. Use `$path status`
    (Codex) or `/path status` to inspect progress without advancing.
 
+For an unattended quick-lane run, invoke `$gsd-path --pre-approve intent,plan`
+in Codex or `/gsd-path --pre-approve intent,plan` on slash-command hosts before
+milestone intent approval. This grants those two gates for one milestone when
+their checks pass. Required answers, failed checks, and other approval gates
+still pause for you. Shipping always needs manual approval.
+
 For a missing skill or an install problem, run:
 
 ```bash
@@ -158,8 +181,8 @@ daemon configuration.
 
 ![Project dashboard showing the history viewer link, milestone progress, expandable evidence, and usage with sample data](docs/images/dashboard-project.png)
 
-*Dashboard screenshots captured from the current source on September 19, 2026,
-using the repository's sample projects.*
+*Dashboard screenshots captured on September 19, 2026, using the repository's
+sample projects; the current project folder layout may differ.*
 
 Open **History & files** to browse project files and archived milestones,
 preview Markdown, or read a file at a selected Git commit. Relative document
@@ -186,8 +209,8 @@ menu-bar icon to open the dashboard directly.
 
 <img src="docs/images/macos-menu-bar.png" alt="OpenGSD Path native macOS panel with sample projects and its bottom toolbar" width="400">
 
-*Screenshots show the current UI with sample project data. The native panel is
-captured in its preview window.*
+*The native panel screenshot uses sample project data and was captured in its
+preview window; the current folder layout may differ.*
 
 ### Install the monitor
 
@@ -362,6 +385,35 @@ default checkout, `gsd-path/M001` branch, and sibling linked worktree. A
 journaled helper performs the approved creation and safely resumes a matching
 partial remote/clone/worktree transaction; the default checkout stays clean.
 
+## Multi-repo milestones
+
+One project can change several repositories in the same milestone. The
+**coordinator** repo holds `.project/` and runs the pipeline; each other repo
+is a **member** listed in `.project/MEMBERS.md`. A member needs a GitHub.com
+`origin` whose default is `main`. See
+[ADR 0002](docs/adr/0002-multi-repo-coordinator.md) for the design.
+
+- Add members at a milestone boundary: ask the router to add an existing repo
+  (`members.py add`) or to create a new one (`members.py add --create`, after
+  you approve the exact owner, name, visibility, and checkout). For optional
+  guard hooks, install them in the member with
+  `npx @opengsd/gsd-path@latest --member-of <coordinator> --project <member>`.
+- The planner gives each member task `repo: <member>`; one task changes one
+  repo. Project Verify runs from the coordinator and reaches a member as
+  `../<member>`.
+- Build works in Path-owned member branches `gsd-path/<project>-M00N` and
+  records each member landing in the coordinator. The final review names each
+  member's reviewed HEAD.
+- Ship closes members in order before the coordinator: `close-members` merges
+  each member in its own `direct` or `pull-request` mode and tags it
+  `milestone/<project>-<archive>`, then the ship commit records each member.
+  A pull-request member waits for you to merge it. The next milestone retires
+  the member branches.
+- `members.py detect --checkout <path>` reports whether a repo is a member.
+
+Out of scope: submodules, one task across two repos, non-GitHub remotes, and
+an atomic close across repos.
+
 ## Handoff contract
 
 ```text

package/RUNTIME.md

@@ -68,7 +68,7 @@ skeptic attempts under `skeptics/`.
 | `skeptics --repo <root> --wave <N> --cycle <C> --child-command '<cmd>' [--wait <s>] [--child-timeout <s>]` | Step 7 skeptic branch: one read-only skeptic per `skeptic_groups` locator in its own sidecar at the recorded review base, briefed with the criterion, every observation, and the cited tasks verbatim; validate with `review_findings.py`, collect, retire, then rerun the helper. `none` without skeptic groups; `escalate` for structural blockers or the cycle cap. The skeptic files stay uncommitted for the fix-task or ruling checkpoint. |
 | `fix-tasks --repo <root> --wave <N> --cycle <C>` | Step 7 batching: one fix task per `review_findings.py collect` batch with the failed criteria and observations verbatim, lint-checked; `escalate` for structural blockers, skeptic groups, cycle cap, or all-refuted. |
 | `complete --repo <root>` | Completion: clean primary at `build/active` (or a crash-left `build/done`), no unfinished wave, the archive-time review cycle check (`discussion_validate.review_cycle_counts`: contiguous cycles, passing last cycle, panel and skeptic artifacts present); `workflow_run.py build-evidence` at HEAD; `pipeline_state.py transition` to `ship/active` with event `build done; final review pending`; checkpoint `build: complete milestone`. |
-| `finish --repo <root> --task-id <id>` | Recover first; return a proven landing without repeating Verify, or verify, land, record, and retire one returned task. Without a dispatch record, derive the isolate from task frontmatter. |
+| `finish --repo <root> --task-id <id>` | Recover first; return a proven landing without repeating Verify, or verify, land, record, and retire one returned task. Without a dispatch record, or when the newest record is settled and its base differs from the task's current in-progress base (a native retry after a driver block), read the primary task's in-progress state; if it lacks a recorded base, use the parallel task isolate's state only if that worktree is authorized. A blocked record at the same base still refuses the retry. A deactivated isolate stays blocked. |
 | `answer --repo <root> --task-id <id> --answer '<text>'` | Append `Orchestrator answer:` to the isolate's task Log; the next `round` redispatches that isolate. |
 | `status --repo <root>` | Every task's newest dispatch record. |
 

package/UPDATE.md

@@ -14,7 +14,7 @@ Pulled new gsd-path / ran npx @opengsd/gsd-path@latest
 └─ Skills feel stale or router shows old behavior?
    ├─ Global install     → install.mjs --update
    ├─ Project-local      → install.mjs --update --local  (from repo root)
-   ├─ Project wiring     → install.mjs --update --project PATH  (keeps contracts and selected runtime)
+   ├─ Project wiring     → install.mjs --update --project PATH  (refreshes the AGENTS.md block; keeps WORKFLOW.md and selected runtime)
    └─ npm only           → npx @opengsd/gsd-path@latest --update
 
 Installed with --hooks and need to refresh wiring
@@ -25,7 +25,10 @@ Installed with --hooks and need to refresh wiring
 Existing project needs guards for the first time
 └─ install.mjs --hooks-init --claude --project PATH
 
-AGENTS.md or WORKFLOW.md template changed upstream
+AGENTS.md template changed upstream
+└─ install.mjs --update --project PATH (replaces only the GSD Path block)
+
+WORKFLOW.md template changed upstream
 └─ Manual diff + merge (installer never overwrites)
 ```
 
@@ -43,7 +46,8 @@ AGENTS.md or WORKFLOW.md template changed upstream
 | Project runtime | Explicit upgrade only | [Runtime lifecycle](DOCS.md#project-runtime-versions) |
 | Native hook settings + git hooks | Yes | `--hooks-refresh-full` (host flag creates missing config) |
 | Guards for an existing project | Yes | `--hooks-init` (preserves project contracts) |
-| `AGENTS.md`, `WORKFLOW.md` | **No** | Manual merge |
+| `AGENTS.md` GSD Path block | Yes | `--update --project PATH` (owner text outside the block is kept) |
+| `WORKFLOW.md` | **No** | Manual merge |
 | `.project/*` (active milestone) | **No** | Pipeline state |
 
 Existing managed skills, including the owned `path` alias, move to
@@ -56,13 +60,32 @@ it or move it aside first. Unrelated skills are never touched. Failed multi-host
 updates roll back all selected targets.
 An initial `--hooks` install merges valid native settings for explicitly selected Claude,
 Codex, or Cursor hosts; other existing project contract and guard files are refused.
-`--update --project PATH` keeps `AGENTS.md`, `WORKFLOW.md`, and `.claude/CLAUDE.md`
-and refreshes managed hook wiring, native settings, and git hooks. For runtime
+`--update --project PATH` replaces the GSD Path block in `AGENTS.md`, keeps
+`WORKFLOW.md` and `.claude/CLAUDE.md`, and refreshes managed hook wiring, native settings, and git hooks. For runtime
 changes or legacy installations, follow the [runtime lifecycle](DOCS.md#project-runtime-versions).
 Use `--hooks-init` to add guards to an existing project without changing its
 `AGENTS.md` or `WORKFLOW.md`. It inspects and merges native configs only for
 the selected hosts; configs for unselected hosts remain untouched.
 
+### Local additions
+
+Skill directories are managed. Updates and reinstalls replace existing managed
+skills with fresh copies; edits and added files inside them stay only in the
+backup described above. To recover your changes, diff each backed-up skill
+against the same skill from the release you had installed. Comparing the backup
+against the new install also includes upstream changes.
+
+Put local rules in project-owned files instead. Add a `## Local rules`
+section to `AGENTS.md` after the `<!-- gsd-path:end -->` line, with
+subsections per phase if needed (for example, "Research: also read X").
+Updates replace only the text between the GSD Path markers, and phase and
+subagent briefs name `AGENTS.md`. Hosts load project instructions differently,
+so confirm your host and its subagents read it. Keep owner rules after the
+block: Codex reads only the first 32 KiB, so text above the block can push
+GSD Path rules out.
+
+Gates are scripts, not an extension point. To change a gate, open an issue.
+
 ---
 
 ## Update skills
@@ -103,8 +126,8 @@ node scripts/install.mjs --update --claude --cursor
 The interactive npm installer detects the old `.gsd-path/runtime/` layout when
 you choose to update project wiring. Choose **Migrate and continue upgrade** to
 migrate first, then update skills and wiring. Cancelling leaves the installation
-unchanged. Migration preserves locally modified files by stopping for you to
-resolve them; it never stages or commits changes.
+unchanged. See [Project runtime versions](DOCS.md#project-runtime-versions)
+for migration safety checks and backups. Migration never stages or commits changes.
 
 For unattended upgrades, migration requires explicit consent:
 
@@ -160,8 +183,8 @@ local edits. Clean source checkouts still refresh before a project update.
 Older unstamped installs show **Unknown — version metadata unavailable**.
 This does not establish that their runtime is outdated or broken. **Update**
 uses the guarded migration for legacy runtime directories and an upgrade for
-version-pinned runtimes. Migration leaves a reviewable Git diff and refuses
-modified or unknown runtime files; the dashboard shows the failure reason.
+version-pinned runtimes. Migration leaves a reviewable Git diff; the dashboard
+shows the failure reason when it stops.
 See [Project runtime versions](DOCS.md#project-runtime-versions) for manual
 migration and preview commands. Use `--doctor --project PATH` to check runtime files.
 
@@ -200,10 +223,36 @@ Details: [HOOKS.md](HOOKS.md)
 
 ## Update project contracts
 
-`AGENTS.md` and `WORKFLOW.md` are installed once with `--project`. A plain install
-**refuses** if they already exist; `--update --project PATH` keeps them unchanged.
+GSD Path owns one marked block in `AGENTS.md`:
+
+```text
+<!-- gsd-path:begin -->
+...GSD Path contract...
+<!-- gsd-path:end -->
+```
+
+You own everything outside the markers. `--project` puts the block first in a
+new or existing `AGENTS.md`; `--update --project PATH` replaces only the
+block. Both refuse:
+
+- a file with unmatched markers or more than one block (fix the markers by
+  hand);
+- a merged file over 32 KiB, because Codex reads only the first 32 KiB. The
+  error prints the file, block, and merged sizes and a command to move the
+  file aside.
+
+Migration from whole-file installs (1.x): an `AGENTS.md` equal to a released
+template becomes a block on the next `--project` or `--update --project`. An
+edited whole-file `AGENTS.md` is refused with a diff: keep your rules, move
+the file aside, rerun, then add your rules after the end marker.
+
+`WORKFLOW.md` and `.claude/CLAUDE.md` (with Claude) are installed once with
+`--project`. A plain install **refuses** if they already exist and prints a
+command to move each to its `.pre-path.md` name. If that name is occupied, it
+asks you to choose an unused name. `--update --project PATH` keeps them
+unchanged.
 
-To adopt upstream template changes:
+To adopt upstream `WORKFLOW.md` changes:
 
 1. Open new templates in the gsd-path repo or npm package
 2. `diff` against your project copies

package/WORKFLOW.md

@@ -75,8 +75,11 @@ cancellation is a blocked result, not a skipped result.
 
 Non-interactive phases auto-advance when their artifacts pass their gates.
 User approval remains required at define, roadmap, plan, final-review patch
-selection, and final shipping checkpoints. Decide auto-advances after its evidence gate
-unless a `NEEDS-USER` decision remains.
+selection, and final shipping checkpoints. Decide auto-advances after its
+evidence gate unless a `NEEDS-USER` decision remains. The opt-in quick-lane
+grant for selected intent or plan gates is described in the
+[router contract](skills/gsd-path/SKILL.md#pre-approval); all other gates
+still ask.
 
 Every user-facing checkpoint follows one handoff shape: **Outcome** states what
 was produced or learned, **Review** links the primary canonical artifact by its
@@ -418,8 +421,9 @@ criterion `met`, `not-met`, or `unverifiable` with checked evidence. Each gap
 reviewer records `pass` or `blocked` for its assigned end-to-end or cross-wave
 risk. List only genuine
 risks that could plausibly fail; never pad the list. The runtime
-runs PLAN.md's project Verify once, stores exact stdout/stderr in the existing
-command/commit ledger, and generates its gap view; other gap
+runs PLAN.md's project Verify and generates its gap view. Single-repo output
+lives in the command/commit ledger; for member milestone evidence and reruns,
+see [S4a1](docs/multi-repo-work.md#slices). Other gap
 reviewers do not re-run it. The orchestrator
 creates one disposable worktree at exact reviewed HEAD
 per reviewer; project commands never run in the primary worktree. Every final
@@ -459,8 +463,8 @@ REPOSITORY.md, LESSONS.md, and the program artifacts (CHARTER.md,
 ROADMAP.md, top-level SYNTHESIS.md) remain active project metadata; a program
 ship also marks the milestone's roadmap entry `Status: shipped` with its
 archive pointer inside the ship commit. MANIFEST.md is
-written by same-directory temporary file plus atomic rename and lists actual
-archive contents, ship date, final verdicts, wave/task/cycle counts, and
+written by same-directory temporary file plus atomic rename and lists
+shippable archive files, ship date, final verdicts, wave/task/cycle counts, and
 carried-forward items. A precommit helper gate validates canonical files, the
 active-root allowlist, metadata, success rows, counts, and exact contents before
 STATE may become shipped.
@@ -472,6 +476,18 @@ real wave-review files, every final artifact names the reviewed HEAD, and Notes
 must be completed. A committed target is immutable and routes only to
 validation.
 
+Ship preparation removes file-free `.claude` staging directories left under the
+active `.project/` tree. Archive preflight also removes them from the current
+uncommitted archive. At the `.project/` top level, ship input and active-root
+checks skip non-pipeline entries only when Git neither tracks nor would add
+them (for example, an ignored, untracked `.DS_Store`). Tracked entries still
+block, and pipeline-owned active paths block even when ignored. Strict checks
+under `.project/` and the current archive skip a regular `.DS_Store` only when
+Git ignores it and does not track it; the manifest omits that file. A tracked
+or non-ignored `.DS_Store` receives normal checks and is listed if archived.
+Other ignored archive files still block shipment, and committed archives remain
+untouched.
+
 One exception: a DOCS-AUDIT.md with pending `planned: no` rulings is copied
 atomically back into a recreated `research/` so the alignment queue survives;
 the archived original keeps full history. Active and archived research may

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengsd/gsd-path",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Disk-backed AI agent pipeline. Docs: DOCS.md (start here), QUICK.md, FULL.md, UPDATE.md",
   "license": "MIT",
   "repository": {
@@ -36,6 +36,7 @@
     "scripts/integration.py",
     "scripts/archive_milestone.py",
     "scripts/bootstrap_repository.py",
+    "scripts/members.py",
     "scripts/detect_project.py",
     "scripts/promote_lookahead.py",
     "scripts/discussion_records.py",
@@ -83,15 +84,15 @@
   },
   "scripts": {
     "install:ci": "npm ci",
-    "check:prereqs": "bash scripts/check-test-prereqs.sh",
-    "test": "node --test tests/*.test.mjs",
+    "check:prereqs": "node scripts/dev/check-prereqs.mjs",
+    "test": "node tests/run-node-tests.mjs",
     "test:smoke": "npm test",
     "test:integration": "npm run test:python",
-    "test:python": "python3 -m unittest discover -s tests",
-    "test:sync": "python3 scripts/sync_skill_resources.py --check",
-    "test:daemon": "PYTHONPATH=daemon python3 -m unittest discover -s tests -p 'test_daemon_*.py'",
-    "verify": "npm test && npm run test:python && python3 scripts/sync_skill_resources.py --check",
-    "verify:release": "npm run verify && python3 scripts/check_trust_evidence.py --repo .",
+    "test:python": "node scripts/dev/py.mjs -m unittest discover -s tests",
+    "test:sync": "node scripts/dev/py.mjs scripts/sync_skill_resources.py --check",
+    "test:daemon": "node scripts/dev/py.mjs --path daemon -m unittest discover -s tests -p \"test_daemon_*.py\"",
+    "verify": "npm test && npm run test:python && npm run test:sync",
+    "verify:release": "npm run verify && node scripts/dev/py.mjs scripts/check_trust_evidence.py --repo .",
     "release:docs": "node scripts/update_release_docs.mjs",
     "release:bump": "node scripts/bump_version.mjs --bump auto",
     "prepublishOnly": "npm run verify:release"