@opengsd/gsd-path 1.0.0 → 1.1.0

package/AGENTS.md

@@ -69,7 +69,10 @@ full-repo suite on a tiny edit outrank the phase brief.
   needs verbal explanation is defective.
 - With no `.project/STATE.md`, route through the bundled
   `scripts/detect_project.py initialize --repo <absolute-root> --template
-  <absolute-state-template>` helper; do not classify from a directory listing
+  <absolute-state-template> --require-git` helper; `route: setup-repository`
+  leaves the invocation folder unchanged and routes to repository setup before
+  state creation or branch binding. Never delete the invocation folder or its
+  state to satisfy bootstrap path checks. Do not classify from a directory listing
   or conversation. Follow its JSON `verdict` and `route`. Reserve `classify`
   for read-only inspection; do not use it as a state-initialization preflight.
 - `.project/STATE.md` tracks phase position. Parse and validate it only with
@@ -98,11 +101,19 @@ full-repo suite on a tiny edit outrank the phase brief.
   deterministic logical task name, and a bounded responsibility. Independent
   briefs may run in parallel up to available child capacity; a dependent
   brief runs as soon as its dependencies complete.
-- Any phase-contract instruction to route, return, or invoke another GSD Path
-  phase is a caller handoff, not permission to trigger an explicit-only
-  skill. If an active router or orchestrator supplied the contract, return
-  control to it. On a direct invocation, report the exact next skill and stop
-  until the user explicitly invokes it.
+- After a phase completes its gate and state update, run the bundled
+  `pipeline_state.py status --repo <absolute-root>` with the routed
+  `--project-dir`. Its `handoff` is the shared phase handoff for chat and the
+  dashboard. Present **Outcome** from `handoff.outcome` plus the completed
+  work; **Review** links the phase artifact, or `handoff.review` when absent.
+  An active router uses `handoff.router_next` for **Next** and follows the
+  returned route. A directly invoked phase uses `handoff.phase_next` and
+  stops. A status or plain-prompt reply uses `handoff.next` and stays read-only.
+  Convert the `$` invocation prefix to the host's slash form when needed.
+  Phase owners still stop for required input and approval before completion;
+  a route is not approval. Return to an active caller instead of invoking an
+  explicit-only sibling skill. Derive the next phase from this result, not
+  from another lane table in prose.
 
 ## Plain-prompt re-entry
 
@@ -118,13 +129,12 @@ full-repo suite on a tiny edit outrank the phase brief.
   authority.
   A plain change request does not authorize work outside the pipeline: make no
   changes and report **Outcome**, link the returned `path` under **Review**, and
-  under **Next** name `next_skill` only for a `run-phase` route; for every other
-  route, report `route.action` and `route.reason`. An explicit request to leave
+  under **Next** use `handoff.next`. An explicit request to leave
   or bypass the pipeline is a user ruling;
   route it through the router's undo or abandon flow instead of editing directly.
 - After any other plain-prompt turn with owned state, rerun the same read-only
   status command immediately before the final response and append the same
-  **Outcome** / **Review** / **Next** handoff with the same exact-route rule.
+  **Outcome** / **Review** / **Next** handoff with the same shared handoff rule.
   Keep an informational turn read-only from start to finish: do not use repository
   mutation tools or run commands that can create or alter files. A GSD Path skill
   already supplies this handoff, so emit it once. With no STATE.md, respond
@@ -337,7 +347,8 @@ full-repo suite on a tiny edit outrank the phase brief.
   approval of the exact owner/name, visibility, default-checkout path,
   `gsd-path/M001` branch, and linked primary-worktree path. Before the
   external action produces an artifact, present those proposed targets as the
-  inline **Review** surface and mark them not yet created. Do not write a
+  inline **Review** surface using the active router's preview contract.
+  Do not write a
   preview file into the invocation directory or another repository. Run the
   bundled bootstrap helper's read-only `preview` command for this evidence.
 - After approval, the bootstrap helper persists the exact targets under the
@@ -355,7 +366,8 @@ full-repo suite on a tiny edit outrank the phase brief.
   build-orchestrator owned.
 - Keep the cloned default checkout clean on the remote default branch. Run the
   pipeline from the linked GSD Path worktree; never initialize `.project/` in
-  the default checkout, reuse an existing branch or path, move an existing
+  the default checkout, reuse an existing branch or path (except an explicitly
+  approved empty linked-worktree folder via `--reuse-empty-worktree`), move an existing
   repository, or recover a partial GitHub creation without the exact approved
   journal and re-verification.
 
@@ -379,6 +391,11 @@ STATE.md.
 
 ## Distribution layout
 
+This section describes the GSD Path source checkout. These source paths and
+the sync command do not apply to an application that only installs GSD Path.
+In a consuming project, resolve roles, templates, and helpers from the active
+installed skill's absolute paths; the application need not contain this layout.
+
 | Path | Purpose |
 |------|---------|
 | `plugin.json` | Agent Plugins manifest (`agent-plugins.org` 1.0.0 schema) |

package/DOCS.md

@@ -70,7 +70,7 @@ node scripts/install.mjs --all --dry-run   # preview — safe to run anytime
 node scripts/install.mjs --all             # apply
 ```
 
-**npm** (no clone — once the package is published to npm):
+**npm** (no clone required):
 
 ```bash
 npx @opengsd/gsd-path --all --dry-run
@@ -263,7 +263,7 @@ Full tree: [README.md](README.md#handoff-contract).
 | --- | --- |
 | Global skills | `node scripts/install.mjs --update` |
 | Project-local skills | `node scripts/install.mjs --update --local` |
-| From npm (once published) | `npx @opengsd/gsd-path@latest --update` |
+| 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 |
 | Health check | `node scripts/install.mjs --doctor [--project PATH]` — read-only; flags missing/stale skills, hook drift, and bad pipeline state |
@@ -311,9 +311,10 @@ an external import bundle, reviews hook coexistence, and hands off to the Path
 router through inspect and define. See **[MIGRATE.md](MIGRATE.md)**.
 
 **Brownfield vs greenfield?**
-The router runs the bundled `scripts/detect_project.py initialize --repo
-<absolute-root>` command, which classifies the project before it creates
-STATE.md for a brownfield or greenfield verdict. A recognized
+After the [startup prerequisites](README.md#the-flow) are met, the router
+classifies the project before it creates STATE.md for a brownfield or
+greenfield verdict. The exact initializer invocation belongs to the
+[phase workflow](WORKFLOW.md#phase-0--inspect-gsd-path-inspect). A recognized
 manifest or source file, qualifying tracked Git file, or qualifying Markdown
 document with a body is brownfield and routes to inspect. A title-only README,
 `LICENSE`/`COPYING`, `.gitignore`, or content only in ignored trees such as

package/FULL.md

@@ -63,10 +63,9 @@ gsd-path  (router: reads STATE.md, runs the next valid phase)
   phases. See the [canonical skill table](DOCS.md#skills-optional).
 
 All skills are **explicit-only** on most hosts — generic “continue the project”
-does not inject the pipeline. In a project with an owned `.project/STATE.md`,
-such a prompt answers read-only with the current handoff and next skill, and a
-plain change request makes no changes (see `WORKFLOW.md`, Plain-prompt
-re-entry). On OpenCode stable, Antigravity CLI, and Kiro, treat explicit
+does not inject the pipeline. For plain prompts and their read-only handoff,
+see the [invocation and handoff rules](README.md#the-flow).
+On OpenCode stable, Antigravity CLI, and Kiro, treat explicit
 invocation as an operating rule.
 
 ### Invocation by host
@@ -79,7 +78,7 @@ 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 once the package is published to npm)
+- **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
   doctor checks; optional for global-only Node installs. `scripts/install.py`
   mirrors global and `--local` install transactions and `--update`; it does not
@@ -160,7 +159,7 @@ See [UPDATE.md](UPDATE.md) for the full updating guide. Quick reference:
 ```bash
 node scripts/install.mjs --update              # global roots with existing install
 node scripts/install.mjs --update --local      # current project only
-npx @opengsd/gsd-path@latest --update                   # from npm, once published
+npx @opengsd/gsd-path@latest --update                   # from npm
 ```
 
 Previous copies move to `disabled-gsd-skills` beside each root. The router may
@@ -184,12 +183,9 @@ Open your agent in the project directory. Invoke the router explicitly.
 
 ### Initial greenfield repository (first milestone)
 
-With no `.project/STATE.md`, a `greenfield` classifier verdict routes to
-**define** immediately. The [DOCS.md FAQ](DOCS.md#faq) owns the exact
-classification rules.
-For an explicit request to create a new GitHub repository, the router first
-previews the repository and linked-worktree targets for approval as described
-in [README.md](README.md#the-flow).
+Follow the [startup and repository setup guidance](README.md#the-flow) first.
+Once setup is complete, a `greenfield` classifier verdict routes to **define**.
+The [DOCS.md FAQ](DOCS.md#faq) owns the exact classification rules.
 
 Define interviews across: problem, users, observable success, scope in,
 scope out (vetoes), constraints, risks, and surfaces. A surface is anything a
@@ -469,7 +465,7 @@ node scripts/install.mjs --update [--local]
 node scripts/install.mjs --hooks-refresh --project /path/to/repo
 node scripts/install.mjs --hooks-refresh-full --project /path/to/repo
 
-# From npm (once the package is published to npm)
+# From npm
 npx @opengsd/gsd-path --all
 npx @opengsd/gsd-path@latest --update
 ```

package/QUICK.md

@@ -40,7 +40,7 @@ first (never writes files):
 node scripts/install.mjs --all --dry-run
 node scripts/install.mjs --all
 
-# From npm, no clone — once the package is published to npm
+# From npm, no clone required
 npx @opengsd/gsd-path --all --dry-run
 npx @opengsd/gsd-path --all
 ```
@@ -87,8 +87,8 @@ In the **project directory**, type explicitly:
 
 Use the [router and phase invocation table](README.md#install-summary) for your host.
 
-“Continue the project” does not advance a phase. With an owned
-`.project/STATE.md` it reports the current handoff and next skill, read-only.
+For plain prompts such as “continue the project,” see the
+[invocation and handoff rules](README.md#the-flow).
 
 **One phase only?** e.g. `/gsd-path-plan` — see skill table in [DOCS.md](DOCS.md#using).
 Need to talk through a question without advancing? Use `/gsd-path-discuss`;

package/README.md

@@ -27,22 +27,140 @@ proof and each host's guard tier.
 | **[UPDATE.md](UPDATE.md)** | Refresh skills, hooks, or contracts |
 | [WORKFLOW.md](WORKFLOW.md) | Phase-by-phase agent SOP |
 | [HOOKS.md](HOOKS.md) | Optional archive/git guard hooks |
+| [daemon/README.md](daemon/README.md) | Dashboard, menu-bar app, and monitoring setup |
+| [RELEASE.md](RELEASE.md) | Maintainer CI and npm release cycle |
 | [GUIDE.md](GUIDE.md) | Pointer to the guides above |
 
+## Install from npm
+
+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.
+The public npm package is **[@opengsd/gsd-path](https://www.npmjs.com/package/@opengsd/gsd-path)**.
+
 ```bash
-# New user
-node scripts/install.mjs --all --dry-run && node scripts/install.mjs --all
-cd your-repo && node scripts/install.mjs --all --project "$(pwd)"
-# In agent: invoke the router (see Install summary below)
+# Interactive installer: choose hosts, install scope, contracts, and hooks
+npx @opengsd/gsd-path@latest
 
-# Already installed
-node scripts/install.mjs --update
-cd your-repo && node scripts/install.mjs --update --project "$(pwd)"   # also refresh .gsd-path/
+# Or preview and install skills for all supported hosts
+npx @opengsd/gsd-path@latest --all --dry-run
+npx @opengsd/gsd-path@latest --all
+
+# Add contracts and the status runtime to your project
+npx @opengsd/gsd-path@latest --all --project /path/to/your-repo
+
+# Update existing installs
+npx @opengsd/gsd-path@latest --update
+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
+`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.
+The npm command installs the latest published release; a source checkout may
+contain newer changes.
+
+### Start your first project
+
+1. Open your project folder in your coding-agent host. Existing repositories
+   need Git; GitHub repository creation and pull-request operations also need
+   an authenticated GitHub CLI (`gh`).
+2. Start or reload the host session so it discovers the installed skills.
+3. Invoke `$path` in Codex, or `/path` on slash-command hosts. The router
+   identifies the project and guides you through the required inputs and approvals.
+4. Resume later from the same folder with the router. Use `$path status`
+   (Codex) or `/path status` to inspect progress without advancing.
+
+For a missing skill or an install problem, run:
+
+```bash
+npx @opengsd/gsd-path@latest --doctor --project /path/to/your-repo
+```
+
+Add `--local` when checking project-local skills, from that project directory.
+See [QUICK.md](QUICK.md) for the first-run checklist and [HOOKS.md](HOOKS.md)
+for optional Git and host guard hooks.
+
+## Dashboard and menu-bar toolbar
+
+The optional **OpenGSD Path monitor** shows your projects without opening each
+project's `.project/` files. It watches the folders you choose and reads project
+state; it does not run pipeline commands or advance phase gates.
+The monitor is a separate install from the npm skills package.
+
+### Dashboard
+
+The project board shows blocked, active, and shipped work, with milestone and
+phase progress, task counts, last activity, and available usage data. Use the
+top toolbar to filter or search projects, refresh status, and open Settings for
+watched folders, plugin management, and appearance.
+
+![OpenGSD Path dashboard showing sample projects, phase progress, and toolbar controls](docs/images/dashboard-board.png)
+
+Click a project to see its milestone roadmap, tasks, success criteria, review
+results, verification history, and activity. Usage includes tokens and turns
+from supported host session logs; cost estimates require model prices in the
+daemon configuration.
+
+![Project dashboard showing milestone progress, criteria, tasks, and usage with sample data](docs/images/dashboard-project.png)
+
+### macOS menu bar
+
+Click the OpenGSD Path menu-bar icon for a compact project list with phase
+meters and task progress. Click a project to open its dashboard page. The
+bottom toolbar opens the dashboard, plugin settings, and watched folders;
+it also provides rescan, appearance, and quit controls. The daemon row shows
+its running state and provides restart and stop controls. Option-click the
+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.*
+
+### Install the monitor
+
+The monitor requires Python 3.9+. From a source checkout, preview the setup,
+then install (macOS/Linux shell):
+
+```bash
+git clone https://github.com/open-gsd/gsd-path.git
+cd gsd-path
+PYTHONPATH=daemon python3 -m gsd_daemon install --dry-run
+PYTHONPATH=daemon python3 -m gsd_daemon install
 ```
 
-Interactive: `npx @opengsd/gsd-path` with no flags opens the OpenGSD wizard (pick hosts, scope, contracts, hooks; dry-run first)
+On Windows, after cloning and entering `gsd-path`, use PowerShell:
 
-npm (once published to npm): `npx @opengsd/gsd-path --all` · Help: `node scripts/install.mjs --help`
+```powershell
+$env:PYTHONPATH = "daemon"
+python -m gsd_daemon install --dry-run
+python -m gsd_daemon install
+```
+
+On Windows, launch the installed shortcut for this session before opening the
+dashboard. It starts automatically at future logins:
+
+```powershell
+Start-Process "$env:APPDATA\Microsoft\Windows\Start Menu\Programs\Startup\gsd-path-daemon.lnk"
+```
+
+Open **http://127.0.0.1:8765**, then use **Settings → Watched folders** to add
+your project folders. The installer creates an isolated Python environment and
+configures autostart. On macOS it also builds and installs the native menu-bar
+app; this requires macOS 12+ and Xcode Command Line Tools (`swiftc`). On
+macOS, use `--no-tray` for the dashboard only. Linux autostart runs the
+dashboard; launch the optional tray separately with
+`~/.gsd-path/venv/bin/gsd-path-daemon tray`. Windows uses a tray-and-dashboard
+Startup shortcut; see the [daemon guide](daemon/README.md) for platform details.
+
+See the [daemon guide](daemon/README.md) for configuration, usage pricing,
+manual startup, and platform setup, or the [macOS guide](daemon/macos/README.md)
+for native menu-bar details.
 
 ## Skills
 
@@ -91,7 +209,7 @@ flowchart TD
     B --> W{"wave loop"}
     W -->|"briefs linted at base SHA"| C["parallel coders, isolated worktrees"]
     C -->|"streaming: dependents dispatch as deps land"| V{"wave review"}
-    V -->|"full — or deep: contract + adversarial lenses"| F{"verdict"}
+    V -->|"full / verify-only / deep"| F{"verdict"}
     F -->|"blocked → criterion triage"| W
     F -->|"pass → next wave"| W
     F -->|"all waves pass"| S["6 · ship — final review"]
@@ -109,6 +227,16 @@ flowchart TD
     A -->|"program complete"| PC["stop"]
 ```
 
+Starting in an empty folder without Git leaves that folder unchanged until
+repository setup. The router asks whether to create a new GitHub repository or
+use an existing repository. For a new repository, approve the exact owner/name,
+visibility, default-checkout path, `gsd-path/M001` branch, and linked-worktree
+path before creation. The starting folder is proposed as the linked worktree,
+with a distinct default checkout beside it, so the agent keeps working where
+it started. Only an approved empty directory can be reused; nonempty folders
+and symlinks remain protected. Pipeline state is created after repository
+setup. See the [repository setup procedure](WORKFLOW.md#new-github-repository-creation).
+
 For an existing Git repository, initialization writes STATE.md first. Before
 entering inspect or define, the router fetches `origin/main`, creates or adopts
 `gsd-path/M001` there, and records the binding in state. Build only uses that
@@ -123,6 +251,8 @@ advance past an unresolved required follow-up.
 
 **Build, under the hood:**
 
+- For intent corrections or structural plan repair during a blocked build,
+  follow the [build recovery contract](skills/gsd-path/references/build-recovery.md).
 - Task briefs are linted against the real base tree (`check_task_briefs.py`)
   before any agent is dispatched, and every coder runs a preflight — paths
   exist or are declared, interface contracts match siblings verbatim — so a
@@ -146,9 +276,11 @@ advance past an unresolved required follow-up.
 
 Invoke the router explicitly to start or advance a phase. Once a project has an
 owned `.project/STATE.md`, a plain prompt such as “continue the project” answers
-read-only with the current handoff and names the next skill; it never advances
-a phase or edits state. Phase skills stop at their handoff; invoke the router
-again to continue.
+read-only with the current handoff and uses the runtime’s `handoff.next`; it
+never advances a phase or edits state. An active router continues across completed phases
+until required input, approval, or a block. A phase invoked directly stops at
+its handoff; invoke the router again to continue. Chat and the dashboard use
+the same executable phase handoff from the status runtime.
 The discussion sidecar is the exception: it can be invoked at any non-shipped
 phase and returns only a durable conversation record.
 
@@ -203,10 +335,14 @@ top-level `SYNTHESIS.md`) remain active project metadata.
 
 ## Install (summary)
 
-Node 18.17+. Project installs also require Python 3.9+. Validates package,
+Node 18.17+ for the Node installer; Python 3.9+ for project installs and pipeline
+helpers. Validates package,
 backs up existing skills, and rolls back on failure.
 **Always** `--dry-run` first when unsure.
 
+The commands below run from a source checkout. For npm, replace
+`node scripts/install.mjs` with `npx @opengsd/gsd-path@latest`.
+
 ```bash
 node scripts/install.mjs --all --dry-run
 node scripts/install.mjs --all
@@ -271,6 +407,7 @@ make install && make verify    # same path as GitHub Actions CI
 | `HOOKS.md` | Guard hooks |
 | `skills/` | Canonical skills and generated aliases declared in [the resource manifest](scripts/skill-resources.json) |
 | `platforms/` | Host dispatch adapters |
+| `daemon/` | Project monitor, dashboard, and tray apps |
 | `scripts/install.mjs` | Installer (npm `gsd-path` bin) |
 | `scripts/install.py` | Python installer |
 | `AGENTS.md` | Operating rules (installed to projects) |

package/RUNTIME.md

@@ -13,6 +13,10 @@ It does not dispatch models or supply owner approvals.
 Use the absolute `workflow_run.py` path in the active skill's scripts directory.
 All commands require `--repo <absolute repository root>`.
 
+Initial inspection also uses `prepare-inspect` and `finish-inspect`. Their
+inputs, receipt handling, and entry conditions are owned by the
+[inspection procedure](skills/gsd-path-inspect/SKILL.md#process).
+
 | Command | Required input | Result |
 | --- | --- | --- |
 | `route` | Optional `--project-dir .project/next` | Canonical route; follow its action even when it blocks or requests recovery. |
@@ -192,7 +196,9 @@ python3 <token_budget.py> admit --ledger <absolute ledger> --task <next logical
 The metric is the host's `output_tokens`, including its reported reasoning output;
 reasoning is not added again. Input and cached input are not included. Resumptions
 reuse the ledger and task identity. Each CLI invocation uses its immutable event
-file. Re-observing that file is idempotent; new invocations accumulate. Native
+file. Re-observing that file is idempotent. For per-invocation versus cumulative
+resume counters, follow the [dispatch accounting contract](platforms/shared-agents/dispatch.md#configured-output-budgets):
+new invocations must charge only new output. Native
 single-invocation child sessions and Claude `--output-format json` usage
 receipts are supported. Resumed native child logs with
 ambiguous cumulative counters fail closed; use separate CLI run receipts instead.

package/WORKFLOW.md

@@ -5,6 +5,13 @@ Idea to shipped code through a gated pipeline. The `gsd-path` router reads
 Every handoff is on disk; the any-phase discussion sidecar also records its
 dialogue and answers on disk. AGENTS.md supplies the shared operating rules.
 
+**Path scope.** `.project/` paths describe the consuming project's artifacts.
+References to `skills/`, `scripts/`, `platforms/`, `RUNTIME.md`, and `HOOKS.md`
+describe the GSD Path source checkout, which an application need not contain.
+For execution in an installed project, resolve each role, template, and helper
+from the active skill's bundled absolute paths. Source-relative links below
+are navigation within the GSD Path source checkout, not installed-file claims.
+
 **Program flow.** When the work is a multi-milestone program, define runs in
 program mode and writes `.project/CHARTER.md` (enduring scope and vetoes),
 research and decide work at program scope, and the roadmap phase slices the
@@ -28,7 +35,7 @@ is the single-milestone flow below.
 
 Use the host-specific child-agent tool defined by the runtime dispatch contract
 bundled in the `gsd-path` skill, or the build contract's
-[dispatch driver](RUNTIME.md#dispatch-driver) when the owner supplies a child
+[dispatch driver](https://github.com/open-gsd/gsd-path/blob/main/RUNTIME.md#dispatch-driver) when the owner supplies a child
 command. Spawn independent work up to the available
 child capacity and batch any remainder. Every spawned agent has isolated
 context, so its brief must include the absolute role path, exact input paths,
@@ -95,13 +102,12 @@ Project installs include the router's read-only status engine at
 On any turn that did not explicitly invoke a GSD Path
 skill, an owned `.project/STATE.md` activates re-entry. Informational prompts
 finish read-only and end with the current **Outcome** / **Review** / **Next**
-handoff. Mutation prompts make no changes and point to the status result's
-`next_skill` only when `route.action` is `run-phase`. Every other route reports
-its exact `route.action` and `route.reason`. The status engine never initializes state
-or advances a phase.
+handoff. Both informational and mutation replies use the status result's
+`handoff.next` for **Next**. Mutation prompts make no changes. The status engine
+never initializes state or advances a phase.
 
 The optional pre-tool guard backs this up where it has deterministic evidence.
-See [HOOKS.md](HOOKS.md#what-gets-blocked) for write restrictions, including
+See [HOOKS.md](https://github.com/open-gsd/gsd-path/blob/main/HOOKS.md#what-gets-blocked) for write restrictions, including
 closed milestone branches and target worktrees. Shell provenance
 cannot prove which skill initiated a command, so the always-loaded AGENTS.md
 contract owns shell cases.
@@ -113,7 +119,11 @@ gate. Resolve and preview the GitHub owner/name, visibility, normal default
 checkout, `gsd-path/M001` branch, and a distinct linked-worktree path.
 Create no repository, checkout, worktree, pipeline state, journal, or preview
 file until the user approves every target; present the pre-creation review
-inline from the bootstrap helper's read-only `preview` result.
+inline from the bootstrap helper's read-only `preview` result. An existing
+empty invocation folder may be the linked worktree with approved
+`--reuse-empty-worktree`; Git populates it in place. Keep the workspace journal
+outside that folder. Preserve nonempty folders and choose another target;
+never delete the invocation folder or its state to pass a preview.
 
 After approval, the bundled bootstrap helper writes an exact transaction
 journal under the approved workspace before mutation. Its `create` command
@@ -137,8 +147,9 @@ at `inspect/active|blocked`. **Output:**
 
 When STATE.md is absent, the router runs the bundled
 `scripts/detect_project.py initialize --repo <absolute-root> --template
-<absolute-state-template>` helper before asking anything and routes from its
-returned JSON. `brownfield` initializes `inspect/active` and routes here;
+<absolute-state-template> --require-git` helper before asking anything and routes from its
+returned JSON. `route: setup-repository` leaves a non-Git folder unchanged and
+asks for repository setup before creating state. `brownfield` initializes `inspect/active` and routes here;
 `greenfield` initializes `define/active` and skips to define; `orphan` blocks.
 Owned state routes by STATE.md without rerunning the helper. Reserve `classify`
 for read-only inspection; do not re-derive a verdict from a directory listing.
@@ -214,8 +225,8 @@ milestone` instead: research and decide run only when the roadmap entry lists
 open questions, and planning writes a Settled-only milestone SYNTHESIS.md from
 the program synthesis before dispatching the planner. The quick lane skips
 research and decide — planning enters directly from `define/done`, writes
-a Settled-only SYNTHESIS.md and a single wave (verify-only review depth
-permitted, at most two tasks) without a planner agent, and the rest of the
+a Settled-only SYNTHESIS.md and a single wave (full or deep review depth,
+at most two tasks) without a planner agent, and the rest of the
 pipeline runs unchanged. A quick plan that outgrows those bounds corrects the
 lane to `standard` and reroutes through research.
 
@@ -366,6 +377,12 @@ build's re-entry transition instead).
 **Input:** the approved plan and tasks. **Output:** committed code, updated
 task files, and wave reviews.
 
+A blocked build returns through the guarded
+[build recovery contract](skills/gsd-path/references/build-recovery.md) when
+approved intent must change or the remaining task inventory needs repair.
+It preserves landed work, re-gates changed contracts, and returns through a new
+plan approval checkpoint. Ship and archived milestones cannot use this path.
+
 The build contract is not restated here. Branch binding, the wave loop, task
 isolation and landing, wave review, fix batching, completion, and milestone
 abandon live only in the canonical
@@ -477,8 +494,7 @@ The ship phase closes the milestone with exactly one commit on the bound
 branch: the shipped STATE.md, the final-review artifacts, and the archive
 move with its MANIFEST.md, staged from `.project/` only, subject
 `ship: M00N — <milestone-slug>` and a body naming `Archive:` and
-`Reviewed-HEAD:`. Every other commit on the bound branch
-belongs to the build orchestrator. The commit must contain only `.project/`
+`Reviewed-HEAD:`. The ship commit must contain only `.project/`
 paths. There is no untracked-project fallback. Every pipeline commit carries
 the subject and field body defined by its canonical phase contract; task-land
 fields live only in the
@@ -645,7 +661,7 @@ with their exact ordered source-file and row list.
   research/evidence-codebase.md   brownfield ground truth (inspect)
   research/DOCS-AUDIT.md     doc-vs-code verdicts and remediation queue
   research/RESEARCH.md       research dispatch/question/output manifest
-  research/evidence-*.md     four required evidence dimensions
+  research/evidence-*.md     evidence for dispatched dimensions; RESEARCH.md records skips
   research/SYNTHESIS.md      decision artifact; authoritative after decide gate
   plan/PLAN.md               waves, config, and project verify
   tasks/T###-slug.md         full contract, clean base SHA, status

package/package.json

@@ -1,8 +1,16 @@
 {
   "name": "@opengsd/gsd-path",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Disk-backed AI agent pipeline. Docs: DOCS.md (start here), QUICK.md, FULL.md, UPDATE.md",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/open-gsd/gsd-path.git"
+  },
+  "bugs": {
+    "url": "https://github.com/open-gsd/gsd-path/issues"
+  },
+  "homepage": "https://github.com/open-gsd/gsd-path#readme",
   "type": "module",
   "bin": {
     "gsd-path": "scripts/install.mjs"
@@ -18,7 +26,9 @@
     "scripts/wizard.mjs",
     "scripts/skill-resources.json",
     "scripts/_common.py",
+    "scripts/build_recovery.py",
     "scripts/state_checkpoint.py",
+    "scripts/roadmap.py",
     "scripts/state_promote.py",
     "scripts/discussion_validate.py",
     "scripts/integration.py",
@@ -43,6 +53,7 @@
     "scripts/loop_run.py",
     "scripts/workflow_run.py",
     "scripts/dispatch_driver.py",
+    "scripts/task_context.py",
     "scripts/lean_verification.py",
     "scripts/token_budget.py",
     "scripts/pipeline_undo.py",
@@ -76,5 +87,8 @@
     "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 .",
     "prepublishOnly": "npm run verify:release"
+  },
+  "devDependencies": {
+    "yaml": "^2.9.1"
   }
 }

package/platforms/shared-agents/dispatch.md

@@ -122,6 +122,12 @@ directory for the full logical session; resumptions reuse it. Record completed
 parent CLI run events and each native child's session events with stable logical
 task names before the next dispatch. The helper reads host counters and refuses
 incomplete or ambiguous usage; never estimate tokens or reset the ledger.
+When the verified CLI adapter reports cumulative counters across `resume`, record
+each later invocation with `--previous-events <previous recorded CLI events>`.
+The helper checks thread identity and records only the new output, preserving the
+raw total and predecessor. Keep that chain in order; never sum cumulative totals.
+Use ordinary `record` for per-invocation counters. An unknown counter convention
+is unproven usage, not permission to guess.
 Run `admit` for the next task and stop dispatch on a blocked result. Preserve
 its output in the dispatch evidence. This gates observed usage only: concurrent
 or in-flight work can overrun before the host reports usage. Codex CLI has no