forge-orkes 0.62.0 → 0.63.0

package/experimental/conventions/source/skills/testing-standards/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: testing-standards
+description: Testing conventions and quality standards across stacks. Use when writing tests, reviewing test quality, setting up test infrastructure, or discussing testing strategy. Covers test structure, mocking patterns, coverage expectations, and common pitfalls.
+---
+
+# Testing Standards
+
+## Core principle
+
+Tests validate **behaviour defined in requirements and acceptance criteria**, not the current implementation. A good test would catch a subtly wrong implementation.
+
+## Test structure
+
+- **Unit tests** (`tests/unit/`): No network, no database, no file system. Fast. Run on every commit.
+- **Integration tests** (`tests/integration/`): Real dependencies. Slower. Run before merge.
+- **Feature tests** (Laravel, `tests/feature/`): HTTP tests against API endpoints with database.
+
+## Naming
+
+Test names read as specifications:
+
+```python
+# Good
+def test_expired_token_returns_401(): ...
+def test_duplicate_spf_record_raises_validation_error(): ...
+
+# Bad
+def test_token(): ...
+def test_spf(): ...
+```
+
+## One behaviour per test
+
+Each test validates one behaviour. Multiple asserts are fine if they check aspects of the same single behaviour:
+
+```python
+# Good: one behaviour, multiple aspects
+def test_parsed_mechanism_preserves_qualifier_and_value():
+    result = parse("~include:example.com")
+    assert result.qualifier == "~"
+    assert result.value == "example.com"
+    assert result.mechanism_type == MechanismType.INCLUDE
+
+# Bad: multiple behaviours
+def test_parser():
+    assert parse("ip4:1.2.3.4") == ...
+    assert parse("include:x.com") == ...
+    assert parse("invalid") raises ...
+```
+
+## Test independence
+
+- Each test is independent. No ordering assumptions. No shared mutable state between tests.
+- Factories over fixtures for entity creation. Override only the fields the test cares about.
+- Group tests by the subject under test, not by the type of assertion.
+
+## Mocking
+
+Mock at interface/protocol boundaries, not at implementation level:
+
+```python
+# Good: mock the Protocol
+class FakeDNSResolver:
+    async def resolve(self, domain: str) -> list[str]:
+        return ["1.2.3.4"]
+
+service = MyService(resolver=FakeDNSResolver())
+
+# Bad: mock internal implementation
+with patch("mymodule.internal_function"):
+    ...
+```
+
+## Coverage expectations
+
+- **80% minimum** on business logic
+- **100%** on critical paths: authentication, authorisation, data validation, financial calculations
+- Don't chase 100% overall. Focus coverage on code that matters.
+
+## Test quality self-check
+
+After writing tests, verify:
+
+1. Would these tests catch a subtly wrong implementation?
+2. Are any tests just re-asserting what the code does (tautological)?
+3. Are error paths and edge cases covered?
+4. If the implementation changed but behaviour stayed the same, would tests still pass?
+5. Are mocks at the right level (boundaries, not internals)?
+
+## Common agent testing mistakes
+
+- **Tautological tests**: Testing that the code does what it does, not what it should do
+- **Missing error paths**: Only testing the happy path
+- **Implementation coupling**: Tests break when refactoring even though behaviour is unchanged
+- **Overmocking**: Mocking so much that the test validates nothing
+- **Modifying tests to match broken implementation**: If tests fail, fix the code, not the tests
+- **Missing security tests**: No tests for auth failures, input validation rejection, or (in multi-tenant apps) tenant isolation
+
+## Security testing
+
+Security-critical code paths require explicit test coverage:
+
+- **Authentication**: test that unauthenticated requests are rejected, expired tokens are rejected, invalid tokens are rejected
+- **Authorisation**: test that users cannot access data they are not entitled to, test that role-based restrictions are enforced
+- **Tenant isolation (multi-tenant apps)**: test that a user from tenant A cannot read tenant B's data
+- **Input validation**: test that malformed input is rejected (oversized payloads, invalid formats, injection attempts)
+- **Fail-closed behaviour**: test that exceptions in auth/validation paths result in denial, not permissive fallthrough
+- **DNS-specific** (when applicable): test that malformed DNS responses are handled safely, circular references are detected, depth limits are enforced
+
+## Language-specific
+
+### Python (pytest)
+- Use `pytest-asyncio` and `@pytest.mark.asyncio` for async tests
+- Use `pytest-mock` / `unittest.mock` for mocking
+- Use `conftest.py` for shared fixtures
+- Use `parametrize` for testing multiple inputs against the same logic
+- `freezegun` or `pytest-freezer` for time. Never `sleep` in a test. Never rely on `datetime.now()` without freezing.
+- `responses` or `httpx.MockTransport` for HTTP. Never a live request in a unit test.
+- Django: `pytest-django` with `@pytest.mark.django_db`. Transactional by default; use `transaction=True` only when the test needs committed data.
+
+### PHP (Pest)
+- Use `it()` syntax for readable test names
+- Use `RefreshDatabase` trait for database tests (not `DatabaseTransactions` unless you know why)
+- Use factories for test data
+- Use `expect()` API for assertions
+- In multi-tenant apps, tenant isolation is explicit: at least one test per tenant-scoped endpoint proves a user from tenant A cannot read tenant B's data.
+- Assert against the response envelope, not the raw array shape. `assertJsonPath` / `assertJsonStructure`, not deep equality on a whole blob.
+- Fake queues, mail, storage, events: `Queue::fake()`, `Mail::fake()`, `Storage::fake()`, `Event::fake()`. Then assert the specific dispatch.
+- Do not hit real external services (DNS, third-party APIs, SMTP). Fake or mock at the boundary.
+
+### Vue (Vitest + Testing Library)
+- Use `render()` from `@testing-library/vue` (or the project's custom render helper in `tests/helpers/`) to mount components. Never use `screen` directly -- destructure queries from the `render()` result.
+- Use `userEvent.setup()` for interactions (click, type, etc.), not native events
+- Prefer semantic queries: `getByRole`, `getByLabelText` over `getByTestId` (except for page-level root elements)
+- Use `within()` to scope queries to a specific element instead of searching the whole component
+- Use `waitFor()` for async assertions, never `setTimeout` or manual delays
+- Use the project's translation helper for text assertions instead of hardcoding strings, where one exists
+- Use resource factories from `tests/factories/` for test data. If no factory exists, create one using `@faker-js/faker` and `fishery`
+- Call `unmount()` at the end of each test
+- Always write a mount-check test before any other tests for a component
+- No snapshot tests for components that change often. Snapshots are for stable output (serializers, formatters), not for UI in flux.
+- Mock at the network boundary (MSW or equivalent), not at the `axios` import.

package/experimental/conventions/source/skills/vue-conventions/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: vue-conventions
+description: Vue.js frontend coding standards. Use when writing, reviewing, refactoring, or modifying Vue components, composables, or TypeScript frontend code. Covers Composition API, Inertia state management, TypeScript patterns, and component structure.
+---
+
+# Vue.js Conventions
+
+## Component style
+
+- Composition API with `<script setup lang="ts">` exclusively. Never Options API.
+- TypeScript required for all components and composables
+- Section order within SFCs: `<script setup>`, `<template>`, `<style scoped>`
+
+## Naming
+
+- Components: PascalCase files and tags (`UserProfile.vue`, `<UserProfile />`)
+- Composables: camelCase with `use` prefix (`useAuth.ts`, `useDomainList.ts`)
+- Props/emits: camelCase in script, kebab-case in template
+- Events: past tense (`@updated`, `@deleted`, not `@update`, `@delete`)
+
+## Script setup order
+
+Follow this order within `<script setup>`:
+
+1. Imports
+2. Props (`defineProps`)
+3. Emits (`defineEmits`)
+4. Composables (`useRouter()`, `useAuth()`, etc.)
+5. Reactive state (`ref`, `reactive`)
+6. Computed properties
+7. Methods/functions
+8. Watchers
+9. Lifecycle hooks (`onMounted`, etc.)
+
+## State management
+
+- Inertia.js handles data fetching and page state via XHR. The backend is the source of truth for application state. Do not introduce a client-side store unless there is a clear reason. (Applies when the project uses Inertia; otherwise follow the project's chosen data layer.)
+- Legacy code may use Vuex -- do not extend Vuex usage. New code should not add new stores.
+- Props/emits for parent-child communication
+- `provide/inject` for deep component trees (sparingly)
+- Never mutate props directly
+
+## TypeScript
+
+- Prefer `type` over `interface` for prop definitions and general types (team preference)
+- Type all refs: `const count = ref<number>(0)`
+- Type composable return values explicitly
+- Use `as const` for literal types
+- Use destructured defaults on `defineProps`. Avoid `withDefaults()` unless necessary (e.g., non-primitive defaults like arrays or objects)
+
+```typescript
+// Correct: type + destructured defaults
+type Props = {
+  domain: Domain
+  isEditing?: boolean
+}
+const { domain, isEditing = false } = defineProps<Props>()
+
+// Avoid when unnecessary: withDefaults
+const props = withDefaults(defineProps<Props>(), {
+  isEditing: false,
+})
+
+// Wrong: untyped or inline
+const props = defineProps(['domain', 'isEditing'])
+```
+
+## Best practices
+
+- Keep components under 300 lines. Extract sub-components beyond that.
+- One component per file
+- Always use `:key` on `v-for` (never index-based keys for dynamic lists)
+- Prefer `computed` over methods for derived data
+- Use `watchEffect` for side effects, `watch` only when you need the old value
+
+## Testing
+
+- Vitest for unit tests
+- `@testing-library/vue` for component testing (use the project's `render()` helper if one exists in `tests/helpers/`)
+- `userEvent` from `@testing-library/user-event` for interactions, not native events
+- Semantic queries: `getByRole`, `getByLabelText` over `getByTestId` (except for page-level root elements)
+- `waitFor()` for async assertions, never `setTimeout`
+- Test behaviour from the user's perspective, not internal state
+
+## Common agent mistakes to avoid
+
+- Don't use Options API — always `<script setup>`
+- Don't skip TypeScript — all components must be typed
+- Don't use index as `:key` in dynamic lists
+- Don't put business logic in components — extract to composables
+- Don't mutate props
+- Don't skip the standard section order in `<script setup>`

package/experimental/conventions/uninstall.sh

@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+# Forge conventions experimental uninstaller.
+# Removes only the skills/rules this pack installs. Selective by stack, like install.sh.
+#
+# Usage:
+#   bash experimental/conventions/uninstall.sh [TARGET] [stack ...]
+#
+#   TARGET   path to the Forge project (default: current directory)
+#   stack    one or more of: laravel python vue testing universal
+#            no stacks given = remove all this pack's files
+
+set -euo pipefail
+
+TARGET=""
+STACKS=()
+ALL_STACKS=(laravel python vue testing universal)
+
+is_stack() {
+  local s="$1"
+  for known in "${ALL_STACKS[@]}"; do
+    [[ "$known" == "$s" ]] && return 0
+  done
+  return 1
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -h|--help) echo "Usage: $0 [TARGET] [stack ...]  (stacks: ${ALL_STACKS[*]})"; exit 0 ;;
+    *)
+      if is_stack "$1"; then
+        STACKS+=("$1")
+      elif [[ -z "$TARGET" ]]; then
+        TARGET="$1"
+      else
+        echo "ERROR: unknown argument '$1'" >&2; exit 2
+      fi
+      shift
+      ;;
+  esac
+done
+
+[[ -z "$TARGET" ]] && TARGET="$(pwd)"
+[[ ${#STACKS[@]} -eq 0 ]] && STACKS=("${ALL_STACKS[@]}")
+[[ -d "$TARGET" ]] || { echo "ERROR: target '$TARGET' does not exist" >&2; exit 2; }
+
+say() { echo "  $*"; }
+
+skills_for() {
+  case "$1" in
+    laravel)   echo "laravel-conventions" ;;
+    python)    echo "python-conventions" ;;
+    vue)       echo "vue-conventions" ;;
+    testing)   echo "testing-standards" ;;
+    universal) echo "" ;;
+  esac
+}
+rules_for() {
+  case "$1" in
+    laravel)   echo "laravel-http.md laravel-services.md laravel-jobs.md laravel-migrations.md" ;;
+    python)    echo "python.md" ;;
+    vue)       echo "vue-inertia.md" ;;
+    testing)   echo "testing.md" ;;
+    universal) echo "code-quality.md testing.md" ;;
+  esac
+}
+
+echo "==> Forge conventions uninstaller"
+echo "    target: $TARGET"
+echo "    stacks: ${STACKS[*]}"
+echo
+
+# Bash 3.2-compatible: space-delimited strings, no namerefs.
+SKILL_LIST=""
+RULE_LIST=""
+contains_word() { case " $1 " in *" $2 "*) return 0 ;; *) return 1 ;; esac; }
+for stack in "${STACKS[@]}"; do
+  for s in $(skills_for "$stack"); do
+    contains_word "$SKILL_LIST" "$s" || SKILL_LIST="$SKILL_LIST $s"
+  done
+  for r in $(rules_for "$stack"); do
+    contains_word "$RULE_LIST" "$r" || RULE_LIST="$RULE_LIST $r"
+  done
+done
+
+removed=0
+for s in $SKILL_LIST; do
+  d="$TARGET/.claude/skills/$s"
+  [[ -d "$d" ]] && { rm -rf "$d"; say "removed skill '$s'"; removed=$((removed + 1)); }
+done
+for r in $RULE_LIST; do
+  f="$TARGET/.claude/rules/$r"
+  [[ -f "$f" ]] && { rm -f "$f"; say "removed rule '$r'"; removed=$((removed + 1)); }
+done
+
+echo
+echo "==> Done. removed: $removed"
+[[ $removed -eq 0 ]] && say "(nothing matched — already absent)"

package/experimental/m10/README.md

@@ -0,0 +1,130 @@
+# Forge M10 — Multi-Agent Orchestration (Experimental)
+
+## Status
+
+**Experimental.** Per [ADR-001](../../../../.forge/decisions/ADR-001-m10-experimental-track.md), M10 ships outside the core Forge gate. The default `create-forge` template ships **zero** M10 files. This installer is opt-in.
+
+Promotion to core requires constitutional amendment after real-world validation.
+
+## M16 Positioning
+
+Chief/Streams is now the preferred user-facing orchestration model. Use the
+Project Chief to show, start, pause, resume, delegate, conflict-check, merge, or
+close concurrent streams. M10 remains useful as an optional backend when a stream
+needs worktree isolation, merge-queue discipline, or optional file-claim checks.
+
+In practice: think in streams, not claims. Let the Chief decide whether M10 is
+the right substrate for a stream.
+
+## What it does
+
+Adds optional multi-agent backend mechanics to a Forge project:
+
+- **Worktree isolation** — each agent session runs in its own `git worktree` under `../<repo-basename>-worktrees/{anchor}/` with a locked branch `forge/{anchor}` (configurable via `orchestration.worktree_root` in `.forge/project.yml`; per-repo by default to avoid cross-repo mixing — see ADR-010).
+- **MCP-coordinated claims** — optional experimental defense-in-depth; agents can call `forge_claim_files` before edits so collisions across concurrent sessions surface before damage.
+- **Auto-merge queue** — clean merges go straight to `main`; conflicts route to the `debugging` skill.
+- **PreToolUse claim-check hook** — defense-in-depth: rejects writes to files claimed by another live session.
+
+See ADR-001..005 + `.forge/research/milestone-10.md` for design rationale.
+
+## Prerequisites
+
+| Tool | Min version | Why |
+|------|-------------|-----|
+| `bash` | 3.2 | Hook + installer |
+| `jq` | any | JSON merging in installer + hook |
+| `sqlite3` | any | Claim store |
+| `node` | ≥ 24 | MCP server runtime (uses built-in `node:sqlite`) |
+| `git` | ≥ 2.48 | Worktree fixes |
+| `git lfs` | ≥ 3.6 (if installed) | Worktree compatibility |
+
+Also: **submodules must be clean pins** — initialized and in-sync with their recorded SHA (`git submodule status` shows a ` ` prefix on every line). Clean pinned submodules (e.g. JUCE, nanovg) are supported: each worktree auto-inits them in `orchestrating` Step 2, reusing the shared `.git/modules` store. Bootstrap refuses only on uninitialized (`-`), divergent (`+`), or conflicted (`U`) submodules — see `source/skills/orchestrating/bootstrap-checks.md` "Submodule handling".
+
+## Install (scripted)
+
+```bash
+bash packages/create-forge/experimental/m10/install.sh /path/to/your/forge-repo
+```
+
+Supports `--dry-run` to preview actions without writing.
+
+Idempotent — re-running emits warnings instead of errors.
+
+## Install (manual)
+
+If you'd rather see exactly what changes:
+
+1. Copy `source/mcp-server/` → `<target>/.forge/.mcp-server/`
+2. Copy `source/hooks/forge-claim-check.sh`, `source/hooks/forge-claim-check-doctor.sh`, `source/hooks/forge-session-id.sh`, and `source/hooks/forge-branch-guard.sh` → `<target>/.claude/hooks/` (`chmod +x`)
+3. Copy `source/skills/orchestrating/` → `<target>/.claude/skills/orchestrating/`
+4. Merge `forge-orchestrator` entry into `<target>/.mcp.json`:
+   ```json
+   { "mcpServers": { "forge-orchestrator": { "command": "node", "args": [".forge/.mcp-server/index.js"] } } }
+   ```
+5. Append the PreToolUse hook **and** the SessionStart hook to `<target>/.claude/settings.json`:
+   ```json
+   "PreToolUse": [
+     { "matcher": "Edit|Write|MultiEdit|NotebookEdit",
+       "hooks": [{ "type": "command", "command": ".claude/hooks/forge-claim-check.sh" }] }
+   ],
+   "SessionStart": [
+     { "hooks": [{ "type": "command", "command": ".claude/hooks/forge-session-id.sh" }] }
+   ]
+   ```
+   Also add the branch-discipline guardrail under `PreToolUse`:
+   ```json
+   { "matcher": "Bash",
+     "hooks": [{ "type": "command", "command": ".claude/hooks/forge-branch-guard.sh" }] }
+   ```
+   The SessionStart hook captures the Claude session id (claim identity); without it the enforcement gate fail-opens (ADR-007). The branch-guard protects the shared main HEAD when worktrees are active (ADR-008) — orchestration-agnostic, independent of the claim layer.
+6. `cd <target>/.forge/.mcp-server && npm install`
+
+## Verify
+
+After install:
+
+1. Restart Claude Code in the target repo.
+2. Approve `forge-orchestrator` when prompted.
+3. Run `/mcp` — confirm `forge-orchestrator: connected`.
+4. Run a no-op `Edit` on any file — confirm hook fires (check `.forge/.mcp-server/server.log` or watch for hook-injection warnings).
+5. Start work normally with `forge` — it now auto-routes (see Usage).
+
+Run the doctor anytime: `bash .claude/hooks/forge-claim-check-doctor.sh`.
+
+## Usage
+
+For new Forge usage, start with Chief/Streams. Ask the Project Chief to start or
+delegate streams, then let it select M10 when a stream needs isolation or merge
+queue support.
+
+Legacy behavior remains available for repos that installed M10 as the primary
+orchestration path: `forge` can route Standard/Full work through `orchestrating`
+(worktree + optional file claims) before `executing` when `orchestration.auto`
+is enabled. You still should not invoke `orchestrating` directly unless you are
+debugging or intentionally using the backend.
+
+- **Quick tier never auto-orchestrates** — a worktree per typo is the wrong trade.
+- **Incompatible repo** → `orchestrating` bootstrap refuses, writes `lifecycle.worktree_mode: refused`, and `forge` continues single-agent. Nothing breaks.
+- **Opt out** per project: set `orchestration.auto: false` in `.forge/project.yml`. `forge` then reverts to single-agent unless you invoke `Skill(orchestrating)` explicitly.
+- **Mid-session** work already running single-agent (active `lifecycle.worktree_mode`) is never re-bootstrapped.
+
+## Uninstall
+
+```bash
+bash packages/create-forge/experimental/m10/uninstall.sh /path/to/your/forge-repo
+```
+
+Preserves `claims.db` (user state) by default. Pass `--purge` to remove it.
+
+## Known issues
+
+See `.forge/research/milestone-10.md` "Sharp edges" section for the canonical list. Headlines:
+
+- **Claude Code #33947** — MCP server stdout buffering on macOS can stall first response. Mitigated by keepalive.
+- **Claude Code #40207** — long-idle MCP servers occasionally drop connection. Server emits 8s keepalive ping as mitigation.
+- **Concurrent SQLite contention** — validated to 2-3 agents; not load-tested beyond.
+- **Worktree on submodule repos** — installer refuses (bootstrap check 3).
+
+## Promotion path
+
+Per ADR-001 Consequences: M10 graduates to core when (a) used by ≥3 real projects without rollback, (b) constitutional Article XIII amendment is proposed and accepted, (c) installer is converted to a default `create-forge` template option (still opt-in at scaffold time, but built-in).

package/experimental/m10/install.sh

@@ -0,0 +1,198 @@
+#!/usr/bin/env bash
+# Forge M10 experimental installer — multi-agent orchestration opt-in.
+# Idempotent. Re-running emits warnings, not errors.
+# Usage: bash install.sh [--dry-run] /path/to/forge-repo
+
+set -euo pipefail
+
+DRY_RUN=0
+TARGET=""
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SOURCE_DIR="${SCRIPT_DIR}/source"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --dry-run) DRY_RUN=1; shift ;;
+    -h|--help)
+      echo "Usage: $0 [--dry-run] /path/to/forge-repo"
+      exit 0
+      ;;
+    *) TARGET="$1"; shift ;;
+  esac
+done
+
+[[ -z "$TARGET" ]] && { echo "ERROR: target repo path required" >&2; exit 2; }
+[[ -d "$TARGET" ]] || { echo "ERROR: target '$TARGET' does not exist" >&2; exit 2; }
+[[ -f "$TARGET/.forge/project.yml" ]] || { echo "ERROR: target is not a Forge project (.forge/project.yml missing)" >&2; exit 2; }
+
+say() { echo "  $*"; }
+do_or_say() {
+  if [[ $DRY_RUN -eq 1 ]]; then echo "[dry-run] $*"; else eval "$*"; fi
+}
+
+echo "==> M10 experimental installer"
+echo "    target: $TARGET"
+[[ $DRY_RUN -eq 1 ]] && echo "    mode:   dry-run (no changes)"
+echo
+
+# Step 1: prerequisite doctor
+echo "==> Prerequisites"
+missing=0
+for tool in bash jq sqlite3 node git; do
+  if command -v "$tool" >/dev/null 2>&1; then
+    say "✓ $tool: $($tool --version 2>&1 | head -1)"
+  else
+    say "✗ $tool: MISSING"
+    missing=1
+  fi
+done
+[[ $missing -eq 1 ]] && { echo "ABORT: install missing tools first" >&2; exit 3; }
+
+# Node ≥ 24 required for built-in node:sqlite (no native deps, no prebuild-install)
+node_ver=$(node --version 2>&1 | head -1)
+node_major=$(printf '%s' "$node_ver" | sed -E 's/^v?([0-9]+).*/\1/')
+if ! [[ "$node_major" =~ ^[0-9]+$ ]] || (( node_major < 24 )); then
+  echo "ABORT: node ≥ v24 required (found $node_ver). MCP server uses built-in node:sqlite." >&2
+  echo "       Install via: nvm install 24 && nvm alias default 24" >&2
+  exit 3
+fi
+echo
+
+# Step 2: copy MCP server
+echo "==> MCP server → .forge/.mcp-server/"
+if [[ -d "$TARGET/.forge/.mcp-server" ]]; then
+  say "skip: .forge/.mcp-server/ already exists"
+else
+  do_or_say "mkdir -p '$TARGET/.forge/.mcp-server'"
+  do_or_say "cp -R '$SOURCE_DIR/mcp-server/.' '$TARGET/.forge/.mcp-server/'"
+  say "copied"
+fi
+echo
+
+# Step 3: copy hooks
+echo "==> Hooks → .claude/hooks/"
+do_or_say "mkdir -p '$TARGET/.claude/hooks'"
+for h in forge-claim-check.sh forge-claim-check-doctor.sh forge-session-id.sh forge-branch-guard.sh; do
+  if [[ -f "$TARGET/.claude/hooks/$h" ]]; then
+    say "skip: $h already exists"
+  else
+    do_or_say "cp '$SOURCE_DIR/hooks/$h' '$TARGET/.claude/hooks/$h'"
+    do_or_say "chmod +x '$TARGET/.claude/hooks/$h'"
+    say "copied $h"
+  fi
+done
+echo
+
+# Step 4: copy orchestrating skill
+echo "==> Skill → .claude/skills/orchestrating/"
+if [[ -d "$TARGET/.claude/skills/orchestrating" ]]; then
+  say "skip: orchestrating skill already exists"
+else
+  do_or_say "mkdir -p '$TARGET/.claude/skills/orchestrating'"
+  do_or_say "cp -R '$SOURCE_DIR/skills/orchestrating/.' '$TARGET/.claude/skills/orchestrating/'"
+  say "copied"
+fi
+echo
+
+# Step 5: merge .mcp.json
+echo "==> .mcp.json registration"
+MCP_FILE="$TARGET/.mcp.json"
+if [[ ! -f "$MCP_FILE" ]]; then
+  do_or_say "cp '$SOURCE_DIR/mcp-server/example.mcp.json' '$MCP_FILE'"
+  say "created .mcp.json"
+elif jq -e '.mcpServers["forge-orchestrator"]' "$MCP_FILE" >/dev/null 2>&1; then
+  say "skip: forge-orchestrator already registered"
+else
+  if [[ $DRY_RUN -eq 0 ]]; then
+    tmp=$(mktemp)
+    jq '.mcpServers["forge-orchestrator"] = {"command":"node","args":[".forge/.mcp-server/index.js"]}' "$MCP_FILE" > "$tmp"
+    mv "$tmp" "$MCP_FILE"
+  fi
+  say "merged forge-orchestrator entry"
+fi
+echo
+
+# Step 6: merge .claude/settings.json hook
+echo "==> .claude/settings.json PreToolUse hook"
+SETTINGS="$TARGET/.claude/settings.json"
+HOOK_CMD='.claude/hooks/forge-claim-check.sh'
+if [[ ! -f "$SETTINGS" ]]; then
+  if [[ $DRY_RUN -eq 0 ]]; then
+    cat > "$SETTINGS" <<'JSON'
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit|NotebookEdit",
+        "hooks": [{ "type": "command", "command": ".claude/hooks/forge-claim-check.sh" }]
+      }
+    ]
+  }
+}
+JSON
+  fi
+  say "created settings.json with PreToolUse hook"
+elif jq -e --arg cmd "$HOOK_CMD" '.hooks.PreToolUse[]?.hooks[]? | select(.command == $cmd)' "$SETTINGS" >/dev/null 2>&1; then
+  say "skip: forge-claim-check.sh hook already registered"
+else
+  if [[ $DRY_RUN -eq 0 ]]; then
+    tmp=$(mktemp)
+    jq '.hooks.PreToolUse += [{"matcher":"Edit|Write|MultiEdit|NotebookEdit","hooks":[{"type":"command","command":".claude/hooks/forge-claim-check.sh"}]}]' "$SETTINGS" > "$tmp"
+    mv "$tmp" "$SETTINGS"
+  fi
+  say "appended PreToolUse hook entry"
+fi
+echo
+
+# Step 6b: register SessionStart hook (captures Claude session_id → claim identity)
+echo "==> .claude/settings.json SessionStart hook"
+SID_CMD='.claude/hooks/forge-session-id.sh'
+if [[ ! -f "$SETTINGS" ]]; then
+  say "[dry-run] settings.json not yet created — SessionStart would be added alongside PreToolUse"
+elif jq -e --arg cmd "$SID_CMD" '.hooks.SessionStart[]?.hooks[]? | select(.command == $cmd)' "$SETTINGS" >/dev/null 2>&1; then
+  say "skip: forge-session-id.sh hook already registered"
+else
+  if [[ $DRY_RUN -eq 0 ]]; then
+    tmp=$(mktemp)
+    jq '.hooks.SessionStart = ((.hooks.SessionStart // []) + [{"hooks":[{"type":"command","command":".claude/hooks/forge-session-id.sh"}]}])' "$SETTINGS" > "$tmp"
+    mv "$tmp" "$SETTINGS"
+  fi
+  say "appended SessionStart hook entry"
+fi
+echo
+
+# Step 6c: register branch-discipline guardrail (PreToolUse on Bash). Orchestration-
+# agnostic — protects the shared main HEAD whenever >1 worktree exists.
+echo "==> .claude/settings.json branch-guard hook"
+BG_CMD='.claude/hooks/forge-branch-guard.sh'
+if [[ ! -f "$SETTINGS" ]]; then
+  say "[dry-run] settings.json not yet created — branch-guard would be added alongside the others"
+elif jq -e --arg cmd "$BG_CMD" '.hooks.PreToolUse[]?.hooks[]? | select(.command == $cmd)' "$SETTINGS" >/dev/null 2>&1; then
+  say "skip: forge-branch-guard.sh hook already registered"
+else
+  if [[ $DRY_RUN -eq 0 ]]; then
+    tmp=$(mktemp)
+    jq '.hooks.PreToolUse += [{"matcher":"Bash","hooks":[{"type":"command","command":".claude/hooks/forge-branch-guard.sh"}]}]' "$SETTINGS" > "$tmp"
+    mv "$tmp" "$SETTINGS"
+  fi
+  say "appended branch-guard PreToolUse(Bash) hook entry"
+fi
+echo
+
+# Step 7: next steps
+cat <<EOF
+==> Done.
+
+Next steps:
+  1. cd '$TARGET/.forge/.mcp-server' && npm install
+  2. Restart Claude Code
+  3. Approve 'forge-orchestrator' MCP server when prompted
+  4. Run /mcp to confirm connection
+  5. Just start work with forge — it now auto-routes Standard/Full work
+     through orchestrating (worktree + claims). No separate invocation.
+
+Install = consent. Opt out per project with 'orchestration.auto: false'
+in .forge/project.yml, or start one explicitly with Skill(orchestrating).
+
+Uninstall: bash $(dirname "${BASH_SOURCE[0]}")/uninstall.sh '$TARGET'
+EOF