@opengsd/gsd-path 1.0.0

package/HOOKS.md

@@ -0,0 +1,273 @@
+# HOOKS.md — Deterministic Guard Hooks
+
+Optional enforcement for pipeline invariants prompt contracts cannot guarantee:
+
+- committed `.project/archive/` trees stay read-only after ship
+- destructive Git operations do not erase recovery state, untracked evidence,
+  or protected refs
+- direct product-file writes do not bypass a routed non-build phase
+- a milestone branch with its canonical ship commit accepts no further edits or commits,
+  even if STATE is later rewritten; writes are checked against the target worktree
+
+Closed branches still allow read-only Git inspection (`status`, `log`, `diff`, plain
+`cat-file` reads of one object, branch and worktree listing) and the router handoff helpers, including
+`git fetch origin`, SHA resolution, and next-base selection. Branch switching remains
+router-owned. The [ship contract](skills/gsd-path-ship/SKILL.md) owns integration
+conflict handling and published-validation recovery.
+
+`cat-file` options are restricted by `CLOSED_LISTING_GIT_OPTIONS` in
+[`scripts/guard_hook.py`](scripts/guard_hook.py); filter and text-conversion forms
+are blocked because they can execute external commands.
+
+**Docs:** [DOCS.md](DOCS.md) (hub) · [UPDATE.md](UPDATE.md) (refresh hooks) · [QUICK.md](QUICK.md) (first install with `--hooks`)
+
+## When to install
+
+| Situation | Recommendation |
+| --- | --- |
+| New repo running GSD Path with shipped archives | **Recommended** with `--project --hooks` |
+| Solo experiment / no ship yet | Optional |
+| Zed-only workflow | Git hooks still help; no pre-tool-use layer |
+| Already shipped milestones you must not corrupt | **Recommended** |
+
+Hooks are **opt-in** — add `--hooks` to a `--project` install. They do not replace
+careful review; they block common accidental violations.
+
+## Install
+
+```bash
+npx @opengsd/gsd-path --claude --project /path/to/repo --hooks
+# or from clone:
+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:
+
+```bash
+npx @opengsd/gsd-path --hooks-init --claude --project /path/to/repo
+```
+
+`--hooks` requires `--project`. Valid existing native settings for explicitly
+selected Claude, Codex, or Cursor hosts are merged, preserving unrelated
+settings and hooks. Other target files are refused if they already exist.
+
+`--hooks-init` also requires `--project` plus at least one host flag or `--all`.
+It creates the managed guard scripts, merges selected native settings, and
+installs Git hooks without reading or writing existing project contracts.
+Native configs for unselected hosts are ignored.
+
+| File | Purpose |
+| --- | --- |
+| `.gsd-path/guard_hook.py` | Pre-tool-use guard (stdin JSON → exit 2 + denial JSON) |
+| `.gsd-path/git_guard.py` | Commit and publication validator |
+| `.gsd-path/runtime/` | Project-local pipeline helpers, including the read-only status engine |
+| `.git/hooks/pre-commit` | Runs `git_guard.py` before commit |
+| `.git/hooks/commit-msg` | Runs `git_guard.py` with commit message |
+| `.git/hooks/pre-push` | Runs `git_guard.py` on every pushed ref update |
+| `.claude/settings.json` | Claude PreToolUse wiring (`claude` target) |
+| `.codex/hooks.json` | Codex PreToolUse wiring (`codex` target) |
+| `.cursor/hooks.json` | Cursor fail-closed preToolUse wiring (`cursor` target) |
+
+Git hooks are written to the repository's **effective** hooks directory,
+resolved with `git rev-parse --git-path hooks`. That honors `core.hooksPath`
+setups (Husky and friends) and linked worktrees (where `.git` is a file).
+Every selected host requires an initialized repository with a resolvable hooks
+directory; otherwise installation stops before writing.
+
+Git hooks work for **any** agent that commits. Native guard wiring denies a tool
+call when its event is malformed or the guard cannot validate it.
+
+Codex [project hooks](https://learn.chatgpt.com/docs/hooks) are installed but do
+not run until Codex trusts the project `.codex/` layer and the exact hook
+definition. Open `/hooks` in Codex, review both, and trust them. Until that
+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).
+
+### Updating after package upgrade
+
+```bash
+npx @opengsd/gsd-path --hooks-refresh --project /path/to/repo
+npx @opengsd/gsd-path --hooks-refresh-full --project /path/to/repo   # + settings/git hooks
+```
+
+`--hooks-refresh-full` refreshes existing managed `.claude/settings.json`,
+`.codex/hooks.json`, and `.cursor/hooks.json`. Add `--claude`, `--codex`, or
+`--cursor` to create a missing config or merge the guard into that selected
+host's valid existing JSON. Unselected foreign configs are not changed. The
+merge replaces only managed guard entries and preserves unrelated entries,
+hook events, and settings. Codex resolves the guard from the Git root; Cursor
+runs its project hook from the project root, so both configs remain valid after
+a clone or move. A full refresh requires the same working interpreter and
+resolved Git hooks directory as the initial install.
+
+See [UPDATE.md](UPDATE.md).
+
+## What gets blocked
+
+**`guard_hook.py`** (pre-tool-use):
+
+- non-read tool actions targeting archived paths or an existing ancestor of
+  the archive tree; shell operands count an ancestor only for deletion or move
+  commands
+- `git reset --hard`, destructive `git clean` modes, force pushes (including
+  `+` refspecs), destructive branch or ref deletion, `git branch -m`,
+  `git worktree remove --force`, `git stash drop`/`clear`, and whole-tree
+  `git checkout -- .`/`git restore .`
+- shell writes (redirections, `tee`, `cp`, `mv`, `rm`, `sed -i`, ...) that
+  target a routing control (`.git`, `.project/STATE.md`, `.project/next`,
+  `.gsd-path`) while `.project/STATE.md` exists
+- repeated assignments to the same shell variable within one command; split
+  these into separate tool calls so write targets can be resolved
+- copies whose destinations, including nested recursive-copy entries, resolve
+  into closed worktrees. Copy sources remain read-only inputs; ordinary safe
+  recursive copies are allowed. Supported variables are expanded before
+  destinations are derived, including contents-copy forms ending in `/.` or
+  `/`. Both lexical entries and resolved targets are checked. Unresolved copy
+  operands, unreadable source trees, directory sources that are symlinks, and
+  source trees containing directory symlinks are denied; use literal directory
+  paths and copy directory links separately
+- shell commands that reference the archive unless the whole command is a
+  recognized standalone read or a single-command invocation of the bundled
+  `pipeline_state.py` / `archive_milestone.py` helper, resolved to a regular file
+  inside the guard-owned `.gsd-path/runtime/` directory (beside `guard_hook.py`
+  in the repository layout), using exactly `python` or `python3` with optional
+  `-B`; non-empty supplied tool working directories are authoritative. Empty
+  strings, including list items, are treated as absent: nested payloads inherit
+  their parent context, with the process cwd used when no directory is supplied.
+  The helper exception refuses chains, pipes,
+  wrappers, substitutions, redirections, and any newline, carriage return, or
+  backslash in the command text. The parsed script path must contain no `$`,
+  backticks, glob characters (`*`, `?`, `[`, `]`), braces, or `..` path components,
+  and must not start with `~`. Quoted spaces in paths and quoted punctuation
+  within arguments, such as the shipment event's semicolon, are allowed
+- deletion or move commands outside a single simple segment, including command
+  chains, pipes, newlines, grouping, directory changes, and command substitution
+- deletion or move commands with any argument outside the literal-path character
+  set: ASCII letters, digits, `.`, `_`, `-`, and `/` (plus a drive prefix and
+  backslashes on Windows). One matching pair of surrounding quotes is allowed;
+  spaces, parameters, wildcards, braces, and tilde paths are denied even when
+  quoted. This also applies to `find -delete` and supported destructive aliases
+- destructive Git commands nested in supported shell and command wrappers
+- archive glob/brace expansions and execution-capable read options such as
+  `rg --pre`
+- direct write, edit, and patch tool calls targeting `.project/STATE.md`,
+  `.project/next/STATE.md`, their protected parent directories, or `.gsd-path/`;
+  product-file calls also require the deterministic build route, including
+  helper-proven parallel task worktrees
+
+Read tools (`Read`, `Grep`, `View`, …) may still open archive paths.
+
+A working directory is archive context only when it is inside an archive.
+Merely containing `.project/archive/` does not put the repository root in
+archive context: `echo guard-probe`, `python3 -m unittest`, and the archive
+helper with `--repo <root>` remain allowed by the archive guard. Deleting an
+archive ancestor, such as `rm -rf .project`, remains blocked. A simple command
+such as `rm -rf scratch` passes the archive check; other guard rules still apply.
+
+**`git_guard.py`** (pre-commit + commit-msg + pre-push):
+
+- modifies, deletes, or renames away tracked archive paths
+- `ship:` commits (case-insensitive) staging paths outside `.project/`
+- on unshipped pipeline lineage (the committed `STATE.md` names a bound
+  `gsd-path/M###` branch that is not `shipped/done`, and HEAD descends from
+  it — the bound branch itself, `gsd-path-task/` branches, sidecars, and any
+  branch cut from them): commits staging paths outside `.project/` (or the
+  guard's own `.gsd-path/` and native hook settings) unless the phase is
+  `build` and they are landing commits as `isolation.py land` writes them —
+  subject `<task id>: <task title>` matching the task file at `Base:`, a full
+  base SHA HEAD descends from, the staged task file, only that task's declared
+  `files:`, and a `Files:` list of exactly the staged paths. Outside build the
+  reviewed HEAD is frozen; product fixes reopen through the patch plan
+- pushes (to any remote) that move a `gsd-path/M###` ref anywhere but its
+  strict ship commit, or delete it while it holds anything else; and pushes of
+  any other ref whose commit carries a `STATE.md` that still owes a ship commit
+  (names a bound branch, not `shipped/done`). The ship state's `branch` must
+  match every bound name in the local and remote refs. Malformed pre-push
+  records and failed object inspection block the push; a present commit
+  without `STATE.md` passes on an ordinary ref. An absent bound ref passes
+  deletion. The authorized publisher is `archive_milestone.py integrate`;
+  the hook checks ref updates, not which client initiated them
+- **allows** adding files to archive during the ship transaction, before the
+  branch closes
+
+These local hooks cover pushes made by plain Git and clients that invoke
+Git with hooks enabled. Creating a PR from an already published ref does not
+run the pre-push hook. A branch cut from `main` carrying `shipped/done` passes;
+if `main` instead carries an unshipped bound state, pushes of branches carrying
+that state remain blocked until the milestone records are repaired through the
+pipeline.
+
+## GitHub-side gate
+
+The guards above stop agents on the developer machine. A person can still
+merge a pull request from a bound branch in the GitHub UI. To surface that on
+the pull request, add a job to the consumer repository's pull-request workflow
+that fails unless a `gsd-path/M*` head is the ship commit at `shipped/done`:
+
+```yaml
+  gsd-path-ship-gate:
+    if: startsWith(github.head_ref, 'gsd-path/M')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+      - run: |
+          gsd_phase=$(sed -n 's/^phase: *\([a-z]*\).*/\1/p' .project/STATE.md | head -1)
+          gsd_status=$(sed -n 's/^status: *\([a-z]*\).*/\1/p' .project/STATE.md | head -1)
+          state="$gsd_phase/$gsd_status"
+          subject=$(git log -1 --format=%s)
+          case "$subject" in "ship: M"*) ship=1 ;; *) ship=0 ;; esac
+          [ "$state" = shipped/done ] && [ "$ship" = 1 ] && exit 0
+          echo "::error::gsd-path: head is $state with subject '$subject'; a gsd-path/M* branch reaches main only through archive_milestone.py integrate"
+          exit 1
+```
+
+The job is advisory until branch protection or a ruleset requires it, which
+GitHub offers on public repositories and paid plans.
+
+## Wire other hosts
+
+Claude, Codex, and Cursor wiring is installed automatically when that target is
+selected. The installer does **not** install a native guard for any other host,
+even where the host has a pre-tool-use API: those hosts are `git-only` in the
+manifest and stay `git-only` after manual wiring, because the installer neither
+writes nor verifies that wiring. To add it yourself, register
+`python3 .gsd-path/guard_hook.py` as a pre-tool-use hook:
+
+| Host | Where | Docs |
+| --- | --- | --- |
+| Copilot CLI | `.github/hooks/*.json` `preToolUse` | [Copilot hooks](https://docs.github.com/en/copilot/concepts/agents/hooks) |
+| Grok | reads `.claude/settings.json` — covered if Claude wiring installed | [Grok hooks](https://docs.x.ai/build/features/hooks) |
+| Qwen Code | `.qwen/settings.json` `PreToolUse` | [Qwen hooks](https://qwenlm.github.io/qwen-code-docs/en/users/features/hooks/) |
+| Kimi CLI | `~/.kimi-code/config.toml` `PreToolUse` | [Kimi hooks](https://moonshotai.github.io/kimi-code/en/customization/hooks.html) |
+| Kiro CLI | agent config `preToolUse` | [Kiro hooks](https://kiro.dev/docs/cli/hooks/) |
+| Antigravity | `.agents/hooks.json` `PreToolUse` | [Antigravity hooks](https://antigravity.google/docs/hooks) |
+| OpenCode | JS plugin `tool.execute.before` | [OpenCode plugins](https://opencode.ai/docs/plugins/) |
+| Zed | no hook API — git hooks only | — |
+
+**Caveats:** The hook cannot prove which skill initiated a shell command or a
+build-phase edit, so AGENTS.md owns those re-entry cases. Grok and Kimi
+fail-open on hook errors by design. Copilot, Kimi, Kiro, and Antigravity may
+not intercept subagent tools — treat coverage as orchestrator-level.
+
+## Troubleshooting
+
+| Symptom | Likely cause |
+| --- | --- |
+| Commit blocked on archive edit | Expected — ship adds to archive; edits after ship are forbidden |
+| `ship:` commit blocked with `app.py` staged | Ship commits may only touch `.project/` |
+| Tool denied editing archive | Pre-tool guard — use active paths, not archive |
+| Hook not running in Cursor | Run `--hooks-refresh-full --cursor --project /path/to/repo` |
+| `--hooks-refresh` rejects an unmanaged guard | Move the foreign guard aside, then rerun refresh; use `--hooks-init` if guards are wanted |
+| `--hooks-refresh` rejects an unmanaged runtime file | Back up or merge that file, move it aside, then rerun refresh |
+
+More: [DOCS.md](DOCS.md#help) · [UPDATE.md](UPDATE.md)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GSD Path contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/MIGRATE.md

@@ -0,0 +1,100 @@
+# Move from GSD Core to GSD Path
+
+Use `gsd-path-migrate` to preserve an existing Core project's context and
+unfinished work, review hook conflicts, then enter Path through inspect and
+define. The first release covers Claude Code and Codex, with either plugin or
+standalone skill installations.
+
+Both products can stay installed. Migration changes which product governs the
+selected project. Core history stays in `.planning/`; Path creates its own
+`.project/` state through the normal router. Core phase positions and completed
+plans do not become passed Path gates.
+
+## Start
+
+Install or update GSD Path using [the install guide](QUICK.md). In the Core
+project, stop active Core work and invoke the migration skill:
+
+```text
+$gsd-path-migrate
+```
+
+On Claude Code, use the installed `gsd-path-migrate` slash command. Give the
+skill the project path and whether Core came from a plugin or standalone skills.
+The skill prepares an external bundle, so it does not dirty the source project
+before Path's branch binding. Do not delete `.planning/` to suppress hooks.
+Preserve any uncommitted work and reach a clean Git baseline using your normal
+commit/stash workflow before binding. Migration does not discard pending edits.
+
+The bundle contains an exact file copy, a hash manifest, and a reviewed
+`IMPORT.md`. The import carries context, constraints, exclusions, decisions,
+unfinished requirements and plan outcomes, with source references. Completed
+summaries remain historical evidence. Contradictions and missing information
+become explicit questions for you.
+
+## Keep both installations
+
+| Installation | Project cutover |
+| --- | --- |
+| Claude Code plugin | Disable the exact Core plugin identifier at local scope, then reload/restart and verify effective state. |
+| Codex plugin | Set the exact Core plugin identifier's `enabled` value to `false` in trusted project configuration, then restart and verify effective state. |
+| Standalone command hooks | Review each Core hook registration. Use the bundled settings helper to gate only that command for the migrated root. Other projects retain the original command. |
+
+Claude example, using the identifier shown by `claude plugin list --json`:
+
+```sh
+claude plugin disable '<core-plugin>@<marketplace>' --scope local
+```
+
+Codex example in the project's `.codex/config.toml`, merging into any existing
+table for that identifier rather than adding a duplicate:
+
+```toml
+[plugins."<core-plugin>@<marketplace>"]
+enabled = false
+```
+
+Check with the host's native plugin list in both the migrated project and a
+separate Core project. Managed/workspace policy may prevent local overrides;
+the skill reports that conflict instead of claiming migration is safe.
+These controls are documented in
+[Claude's plugin reference](https://code.claude.com/docs/en/plugins-reference)
+and [Codex's configuration reference](https://learn.chatgpt.com/docs/config-file/config-reference).
+
+Plugin disabling does not remove separately installed hooks or skills. Review
+user, project and local settings, status-line commands and inherited instruction
+files. Preserve project-specific rules. Replace Core-only workflow routing with
+Path's installed contracts; keep a copy and record every removed Core instruction
+in the import. Continue using the explicit Path skill names in migrated projects.
+
+## Review and rollback
+
+The standalone settings helper prepares a private receipt before writing. It
+records the exact selected command and original file bytes. After review, apply
+the receipt; restore it to roll back. Changes made since the receipt was prepared
+block application or restoration. With several changes to one settings file,
+apply each before preparing the next and restore in reverse order. Close host
+sessions and settings editors during these writes.
+
+Keep both the installed helper path and its planning-time Python interpreter
+available while hook settings reference them. Restore every receipt before
+uninstalling/moving Path or deleting that interpreter or its virtual environment.
+For symlink-managed settings, pass the resolved real file path to the helper;
+it deliberately refuses symlink paths and files with multiple hard links. Each
+separate migrated worktree needs its own scope. A missing or unclear event `cwd`
+keeps the original Core hook active. Only Claude Code and Codex command-hook
+protocols are covered; other hosts require separate verification.
+
+Review `IMPORT.md` before handing it to `$gsd-path`. Path inspects the code,
+checks the supplied evidence, and asks you to approve intent. Every remaining
+Core outcome must appear in that intent or have an explicit disposition from
+you. Keep the bundle available for the handoff. When inspect finishes, invoke
+define with the absolute IMPORT.md path again, using the command saved in its
+Handoff section. This is required in a fresh session too: the router does not
+carry the external path into define automatically. Define records the source
+path in its intent draft. The skill does not approve,
+build, ship, or publish your project on your behalf.
+
+Preparation and hook-command tests do not prove every installed host policy.
+The skill requires effective-state and hook checks in your target environment
+before declaring cutover complete.

package/QUICK.md

@@ -0,0 +1,146 @@
+# GSD Path — Quick Start
+
+**~5 minutes to installed and running.**
+
+| More | Doc |
+| --- | --- |
+| Hub (install · use · understand · update) | [DOCS.md](DOCS.md) |
+| Full walkthrough | [FULL.md](FULL.md) |
+| Upgrading | [UPDATE.md](UPDATE.md) |
+
+## What you get
+
+One router skill drives a gated pipeline: inspect → define → research → decide →
+plan → build → ship. Every handoff lives in `.project/` so any session can resume from disk.
+
+**Hosts:** Codex, Claude Code, Grok, OpenCode, Copilot CLI, Qwen, Antigravity,
+Cursor, Zed, Kiro, Kimi Code.
+
+---
+
+## Checklist
+
+```text
+[ ] 1. Install skills (step 1)
+[ ] 2. Install project rules in your repo (step 2) — skip if repo already has AGENTS.md
+[ ] 3. Restart agent session
+[ ] 4. Open repo in agent; invoke router (step 3)
+[ ] 5. Approve gates as they appear (step 4)
+```
+
+---
+
+## 1. Install skills
+
+**Node 18.17+. Project installs in step 2 also require Python 3.9+.** Preview
+first (never writes files):
+
+```bash
+# From a clone of this repository (primary path)
+node scripts/install.mjs --all --dry-run
+node scripts/install.mjs --all
+
+# From npm, no clone — once the package is published to npm
+npx @opengsd/gsd-path --all --dry-run
+npx @opengsd/gsd-path --all
+```
+
+Only hosts you use:
+
+```bash
+node scripts/install.mjs --claude --cursor
+```
+
+Team pins skills in the repo? See [DOCS.md — Installing](DOCS.md#installing) (`--local`).
+
+---
+
+## 2. Install project rules
+
+From your repo:
+
+```bash
+cd /path/to/your/repo
+node scripts/install.mjs --all --project "$(pwd)"
+```
+
+Installs `AGENTS.md`, `WORKFLOW.md`, and `.gsd-path/runtime/`
+(+ `.claude/CLAUDE.md` if Claude is selected).
+If those managed files already exist, a plain install **refuses and installs
+nothing** — use `--update --project PATH` to refresh skills and `.gsd-path/`
+while keeping your contracts, and merge project-contract changes by hand
+([UPDATE.md](UPDATE.md)).
+
+**Optional** archive/git guards:
+
+```bash
+node scripts/install.mjs --claude --project "$(pwd)" --hooks
+```
+
+[HOOKS.md](HOOKS.md)
+
+---
+
+## 3. Invoke the router
+
+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.
+
+**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`;
+Codex invokes it as `$gsd-path-discuss`.
+
+---
+
+## 4. Approve gates
+
+| When | You |
+| --- | --- |
+| Define | Answer; approve playback |
+| Decide | Resolve `NEEDS-USER` |
+| Plan | **Approve wave summary** before build |
+| Build | Escalations only |
+| Ship | Approve patch waves if blocked; approve archive and ship when green |
+
+---
+
+## 5. Resume
+
+Invoke the router again. Don’t hand-edit `.project/` mid-run.
+
+---
+
+## Later
+
+```bash
+node scripts/install.mjs --update                           # refresh skills
+node scripts/install.mjs --update --project "$(pwd)"        # refresh .gsd-path/; keeps contracts
+node scripts/install.mjs --hooks-refresh --project "$(pwd)"  # guard scripts
+```
+
+[UPDATE.md](UPDATE.md)
+
+---
+
+## Phase map
+
+```text
+inspect (brownfield) → define → research → decide → plan → build → ship
+```
+
+Artifacts: [README.md](README.md#handoff-contract)
+
+---
+
+## Quick troubleshooting
+
+| Issue | Fix |
+| --- | --- |
+| Skills missing | Restart agent session |
+| Router idle or plain prompt only reports status | Use `$gsd-path` or `/gsd-path` explicitly |
+| Install failed | Read error; try `--dry-run` |
+| Need more detail | [DOCS.md](DOCS.md) or [FULL.md](FULL.md) |