@opengsd/gsd-path 1.3.1 → 1.5.0

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
@@ -153,9 +176,10 @@ a global update does not update project runtimes. Use the project's **Update**
 button to refresh its runtime and existing guards. Install and update actions
 show progress, success or failure, and installer output.
 
-If the daemon's plugin source checkout has local changes, project Update uses
-that local build and says so in its result. It does not pull remote changes over
-local edits. Clean source checkouts still refresh before a project update.
+Project Update refreshes the daemon's plugin source first. With the
+[git source](daemon/README.md#plugin-lifecycle), a clone that has local changes
+is used as that local build, and the result says so. It does not pull remote
+changes over local edits.
 
 Older unstamped installs show **Unknown — version metadata unavailable**.
 This does not establish that their runtime is outdated or broken. **Update**
@@ -200,10 +224,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
@@ -220,6 +223,20 @@ vetoes and corrections verbatim. Unresolved items remain tagged `RESEARCH` or
 first and presented as settled coverage for correction; the interview covers
 only its gaps and contradictions.
 
+Once the success criteria are drafted, define runs the spec-reach probes
+([spec-probes.md](skills/gsd-path/references/spec-probes.md)). The edge probe
+walks each criterion through a closed edge taxonomy (boundary, adjacency,
+empty, encoding, ordering, precision, idempotency, concurrency) and records
+the user's ruling per applicable edge in INTENT.md `## Edge coverage`:
+`criterion SCn` (stated in a success criterion), `held-out` (a named test
+pins it), or `dismissed` with a reason. The prohibition probe asks what each
+criterion must never silently become and records kept items in
+`## Prohibitions` as `criterion SCn`, `judgment`, or `dismissed`. Define
+never rules on an edge itself. `scripts/check_handoffs.py intent` checks
+both tables before every approval question, and the `define/done` transition
+refuses an intent whose tables are incomplete. An INTENT.md without these
+sections predates the probes and is not rechecked.
+
 At approval define classifies the milestone lane in INTENT.md: `quick`
 when scope fits at most two deliverable-sized tasks in one wave with no open
 questions and no cross-wave risk; otherwise `standard`. Milestone mode — a
@@ -340,6 +357,9 @@ by — which that task must own, in the same wave as the capability behind it.
 `check_handoffs.py final` then requires each of those criteria to name its
 surface in FINAL.md with the walkthrough as its Check, so a surface criterion
 cannot be marked `met` on internal test output.
+Every `held-out` edge gets a PLAN.md `## Held-out checks` row naming the task
+and test file; that test is in the task's files, its Verify runs it, and its
+Acceptance criteria state the edge id and ruling.
 `scripts/check_handoffs.py plan` gates the table; `wave` and `final`
 require a verdict per owned SC id. Acceptance criteria,
 owned SCs, and Verify are the contract; the coder owns
@@ -414,12 +434,17 @@ surface walkthroughs, in its existing review. The runtime proves freshness and
 generates FINAL.md from that record. Dispatch an integration reviewer only when
 that proof is incomplete or stale; dispatch gap reviewers only for uncovered
 cross-wave risks through the shared capacity-aware contract. The integration reviewer marks each success
-criterion `met`, `not-met`, or `unverifiable` with checked evidence. Each gap
+criterion `met`, `not-met`, or `unverifiable` with checked evidence. A criterion
+tagged by a `held-out` edge or `judgment` prohibition is `met` only when its
+evidence cites every tag id; otherwise the reviewer records `unverifiable`
+(insufficient spec evidence) and `check_handoffs.py final` refuses a `met`
+that skips a tag. 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 +484,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 +497,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.1",
+  "version": "1.5.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",
@@ -76,22 +77,25 @@
     "skills/",
     "platforms/",
     "AGENTS.md",
-    "WORKFLOW.md"
+    "WORKFLOW.md",
+    "!**/__pycache__/**",
+    "!**/*.pyc"
   ],
   "engines": {
     "node": ">=18.17"
   },
   "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",
+    "check:locks": "node scripts/dev/py.mjs scripts/check_lock_usage.py",
+    "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"

package/platforms/shared-agents/dispatch.md

@@ -44,6 +44,19 @@ use exactly one matching branch:
   create another worktree. Encode task dependencies explicitly; launch
   independent children concurrently up to the host's advertised
   concurrent-subagent capacity.
+- A `muse.subagent_spawn` tool (with `muse.subagent_wait`,
+  `muse.subagent_read_result`, and `muse.subagent_send_message` siblings) is
+  Muse Code. Omit `subagent_type` (general-purpose, full capability), pass the
+  logical task name as `task_name` and `role`, and the complete brief as
+  `objective`. Never set `worktree_isolation`. Keep the returned
+  `subagent_id`; send a correction to a still-live child with
+  `muse.subagent_send_message` mode `followup` and the complete new prompt,
+  otherwise start a fresh child. Collect with `muse.subagent_wait`
+  (`wait_for: task_terminal`) then `muse.subagent_read_result`; on
+  `root_capacity_exhausted`, wait for a child to finish and retry. Spawn has no
+  model or effort argument, so record no such capability. If only
+  `muse.workflow` is exposed (untrusted workspace), do not script or inline
+  the work; stop and report that the workspace must be trusted.
 
 For every branch: