forge-orkes 0.14.0 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.14.0",
+  "version": "0.17.0",
   "description": "Set up the Forge meta-prompting framework for Claude Code in your project",
   "bin": {
     "create-forge": "./bin/create-forge.js"

package/template/.claude/agents/planner.md

@@ -51,6 +51,9 @@ requirements:
 Mark unknowns `[NEEDS CLARIFICATION]` — never guess.
 
 ### 5. Decompose Tasks
+
+**Cross-layer first:** if this phase introduces/changes an interface one layer produces and another consumes (litmus: would an isolated agent have to guess the other's shape?), pin the delta in `contract.md` and either tag tasks `layer:` (Tier 1, one plan) or split into producer plan-NNa (pins contract) + consumer plan-NNb (`depends_on` the *frozen contract*, builds in parallel) -- Tier 2. See planning skill Step 6.1.
+
 ```xml
 <task type="auto|manual">
   <name>{Verb} {thing} {detail}</name>
@@ -109,3 +112,4 @@ must_haves:
 - **Horizontal slicing**: models->routes->UI (prefer vertical)
 - **Gold-plating**: Beyond requirements
 - **Guessing**: Fill unknowns instead of `[NEEDS CLARIFICATION]`
+- **Guessing a cross-layer shape**: splitting layers without pinning `contract.md` first -- the consumer ends up guessing the producer's shape. Pin the contract, then split.

package/template/.claude/skills/architecting/SKILL.md

@@ -7,6 +7,17 @@ description: "Make architectural decisions: choose frameworks, design data model
 
 Make architectural decisions. Document rationale. Consider alternatives.
 
+## Vertical-Slice Bias
+
+Architectural decisions should preserve the planning skill's slice-first decomposition. Favor designs that let the team ship thin end-to-end user journeys early:
+
+- **Prefer feature-folder layouts** (`src/features/signup/{ui,api,data}.ts`) over strict layer-folder layouts (`src/models/`, `src/api/`, `src/components/`) when the project allows. Layer-folder layouts are not banned -- but they invite horizontal decomposition.
+- **Avoid framework choices that force big-bang integration.** If picking framework A means UI cannot be wired until the whole data layer ships, that's a red flag -- document the trade-off in the ADR's Consequences section.
+- **Contracts before completeness.** Define the minimal API contract a single slice needs. Resist designing the full API surface upfront -- successive slices extend it.
+- **Data models grow per slice.** Start with the fields slice 1 needs. Add columns/entities as later slices require. Reject "design the whole schema first" unless a `slice_exception: data_migration` phase is planned.
+
+When an architectural decision conflicts with vertical slicing (e.g., a framework that requires full backend before any UI is testable), surface the conflict explicitly in the ADR's **Trade-Offs** section.
+
 ## When to Use
 
 - Choosing a framework, library, or major dependency

package/template/.claude/skills/debugging/SKILL.md

@@ -7,6 +7,20 @@ description: "Systematic debugging when tests fail, features break, errors are c
 
 Every hypothesis tested, every dead end recorded.
 
+## Entry Path: Merge Conflict [Experimental — M10]
+
+Invoked by `orchestrating` skill when `forge_queue_commit` returns `status: conflict`.
+
+**Payload:** `{ conflicted_files: [...], base_sha, messages: [...], branch }`
+
+**Workflow:**
+1. Inside agent's worktree: `git fetch origin main && git rebase ${base_sha}` (use payload ref).
+2. For each `conflicted_files[]` entry: inspect both sides via `git status` + `git diff`. Resolve per task context (or prompt user when intent unclear).
+3. After all resolved: `git add <files>` then `git rebase --continue`.
+4. Re-invoke `Skill(orchestrating)` with `action: retry-teardown` → orchestrating re-calls `forge_queue_commit`.
+
+**Abort path:** if user aborts or resolution stalls, leave worktree in conflicted state and append `{ kind: "merge_conflict", branch, files }` to `lifecycle.blockers[]` in `.forge/state/milestone-{id}.yml`. Single-agent debugging entry paths below are unaffected.
+
 ## Scientific Method
 
 1. **Observe**: Exact behavior — error, repro steps, when it started

package/template/.claude/skills/executing/SKILL.md

@@ -35,6 +35,16 @@ Execution-phase operational guidance below supplements the rules — it does not
 ### Scope Boundary
 Only fix issues DIRECTLY caused by the current task. Pre-existing warnings, tech debt, unrelated bugs → log to `.forge/deferred-issues.md`.
 
+### Slice Integrity (Execution-Side)
+
+The planning skill enforces vertical slicing at plan-creation time. Executor responsibility: do not silently re-introduce horizontal decomposition.
+
+- **Do not split a slice plan into "backend now, UI later"** under Rule 1/2/3. If the UI half of a slice is broken, fix it -- do not defer it. Deferring the UI breaks the slice's user-observable truth.
+- **Do not collapse the slice into a stub** to pass verification. `key_links` must be real (component actually hits handler; handler actually persists). Stubbed links fail the verifying gate.
+- If a slice genuinely cannot ship end-to-end (e.g., external API blocker), invoke **Rule 4 -- STOP, ask user.** Options: redefine the slice, declare a `slice_exception:` and continue, or defer the phase. Do not autonomously ship half a slice.
+
+This rule does NOT override the 3-strike limit or scope boundary -- it sits alongside them.
+
 ## Native Task Tracking
 
 Use `TaskCreate`/`TaskUpdate`/`TaskList` for in-session visibility. `.forge/state/milestone-{id}.yml` remains the cross-session source of truth.
@@ -95,6 +105,30 @@ feat(auth-01): implement JWT-based login
 - Include integration test for login flow
 ```
 
+## Multi-Agent Claim Convention [Experimental — M10]
+
+**Trigger:** active milestone state has `lifecycle.worktree_mode: active` (set by `orchestrating` skill). If absent or any other value → skip this section entirely; single-agent behavior unchanged.
+
+**Pre-edit:** before the first `Edit` / `Write` / `MultiEdit` / `NotebookEdit` in a task, call MCP tool:
+
+```
+forge_claim_files {
+  session_id: lifecycle.session_id,
+  files: [<absolute paths from task <files> manifest>],
+  ttl_seconds: 1800,
+  reason: "executing m{M}-{N} task <name>"
+}
+```
+
+**Branches:**
+- **Full claim granted** → proceed with edits.
+- **Partial rejection** → surface `rejected[].file`, `rejected[].owner_session`, `rejected[].expires_at` to user. Three options: **abort** task, **skip** rejected files (continue with granted subset), **wait** then retry after `expires_at`.
+- **`DB_UNAVAILABLE`** → log warning, proceed. PreToolUse claim-check hook is defense-in-depth — coordination degrades to best-effort, isolation (worktree) still holds.
+
+**End of task:** call `forge_release_claims { session_id, files: [...] }` after final commit. Plan-complete bulk release handled by `orchestrating` teardown.
+
+See ADR-003 and `.claude/skills/orchestrating/SKILL.md`.
+
 ## Verification Gate
 
 After each task commit, run configured verification commands. Mechanical — not optional.
@@ -221,7 +255,21 @@ Log to `.forge/state/index.yml → desire_paths` (global, not per-milestone):
 - **User corrections**: Repeated correction matching a prior one → `user_correction`, increment count
 - **Agent struggles**: Multiple attempts or user guidance needed → `agent_struggle`
 
+## Cross-Layer Seam Check
+
+**Trigger:** the phase was split by planning Step 6.1 into a **Tier-2** producer plan-NNa + consumer plan-NNb (both carry a `contract:` frontmatter path pointing at the same `contract.md`). Single-plan / Tier-1 (`layer:` tag, no split, contract honored inline) → skip; no seam check needed.
+
+After **both** layer plans are committed, the executing flow owns one final **seam-check task** — there is no standing agent for this:
+
+1. **Read** the phase `contract.md` — `delta`, `producer_layer`, `consumer_layer`, `seam_check`, `status` (should already be `ratified` from the planning Tier-2 gate).
+2. **Merge** the layer branches/worktrees. If `lifecycle.worktree_mode: active`, the `orchestrating` teardown merges them; otherwise merge the sibling plan branches into the phase working tree.
+3. **Verify the seam** — run the assertion named in `contract.md` `seam_check` (a test, a type-check, or a structural grep) to prove the shape the producer emits matches what the consumer built against per `delta`.
+4. **Match** → commit the merge: `feat({phase}): seam check {integration_point}`. Contract stays `status: ratified`.
+   **Mismatch** → the consumer guessed wrong against a frozen contract → **Rule 1** fix on the consumer side. If the *contract itself* is wrong (producer can't emit the agreed shape) → **Rule 4** STOP, re-ratify with the user before proceeding.
+5. Leave the contract at `status: ratified` — the `reviewing` skill folds `delta` into the governing ADR (`status: absorbed`) at milestone landing. Do **not** absorb here.
+
 ## Phase Handoff
 1. Confirm persistence — summary documented, commits made, state updated, desire paths logged
-2. Set `current.status` to `verifying`
-3. Recommend: *"Tasks committed, state updated. `/clear` then `/forge` to continue with verifying."*
+2. **Run the Cross-Layer Seam Check** (above) if this phase was a Tier-2 contract split
+3. Set `current.status` to `verifying`
+4. Recommend: *"Tasks committed, state updated. `/clear` then `/forge` to continue with verifying."*

package/template/.claude/skills/forge/SKILL.md

@@ -188,6 +188,8 @@ Tier + state → invoke via `Skill` tool. All phases use `Skill()`.
 
 **CRITICAL: NEVER `EnterPlanMode`.** "Planning" = `Skill(planning)`. Native plan mode writes wrong format, bypasses gates + state.
 
+**Experimental:** if user invokes `orchestrating` skill (M10) and repo has it installed (`.claude/skills/orchestrating/` present + MCP server + claim-check hook), route through it **before** `executing` to bootstrap multi-agent worktree. Skill is opt-in per ADR-001; absent install → fall through to standard routing.
+
 ### Auto-Routing (Always Deterministic)
 
 **No menus.** Applies on first run and resume. Deterministic. Brief → route. Choices only at `complete` or corrupted.

package/template/.claude/skills/initializing/SKILL.md

@@ -225,6 +225,19 @@ Glob: src/**/index.{ts,tsx,js}  # barrel exports
 Grep: src/ for "import.*from.*@/"  # path aliases
 ```
 
+### Step 3.5: Architectural Layers
+
+Detect distinct layers that hand a typed interface across a boundary — feeds the cross-layer contract detection in planning Step 6.1. A layer = a directory whose code is *produced for* or *consumed by* another (engine↔ui, core↔plugins, api↔web, native↔bindings).
+
+```bash
+Bash: ls -d */ src/*/ 2>/dev/null              # top-level + src subdirs as layer candidates
+Grep: cross-boundary imports (e.g. ui importing engine types, generated bindings, ABI/descriptor/schema files)
+```
+
+A single cohesive codebase with no internal producer→consumer boundary → **not** layered; leave `layers: []` (Step 6.1 no-ops). Only flag layers when one directory's output is another's typed input.
+
+Present detected layers for confirmation: *"Detected layers: [{name → path}]. These hand interfaces across a boundary — confirm or correct."* Confirmed 2+ → written to `project.yml` `layers:` and seeded into `.forge/contracts/index.yml` at Finalize.
+
 ### Step 4: Present
 
 *"Project: {name} — {description}
@@ -269,6 +282,12 @@ User describes project → `.forge/project.yml`: name, goal, stack, constraints,
 
 Validate each term against `.forge/templates/interface-detection.md` type vocabulary. On unrecognized term, prompt: *"Did you mean [closest match]? Valid: browser | cli | api | desktop | native-apple | none."* Write validated answer as `interface: [...]` in project.yml.
 
+### Step 1.6: Architectural Layers
+
+*"Will this project have distinct layers that hand a typed interface across a boundary (e.g. engine ↔ ui, core ↔ plugins, api ↔ web)? List them as name → path, or 'no' for a single-layer project."*
+
+2+ layers → write `layers:` to project.yml + seed `.forge/contracts/index.yml` at Finalize. Otherwise `layers: []` (planning Step 6.1 no-ops).
+
 ### Step 2: Design System
 
 *"UI library?"*
@@ -314,10 +333,11 @@ User selects per stack.
 
 ## Finalize
 
-1. Write `.forge/project.yml` (all info + `verification`)
+1. Write `.forge/project.yml` (all info + `verification` + `layers`)
 2. Write `.forge/constitution.md`
 3. Write `.forge/design-system.md` (if configured)
-4. Init state:
+4. Write `.forge/contracts/index.yml` (only if `layers:` has 2+ entries) — copy `.forge/templates/contracts-index.yml`, fill `layers:` from the confirmed list, leave `integration_points:` empty (first cross-layer phase populates them via planning Step 6.1)
+5. Init state:
    - `.forge/state/index.yml`:
      ```yaml
      milestones:
@@ -339,7 +359,7 @@ User selects per stack.
        task: null
        status: not_started
      ```
-5. Templates as needed
+6. Templates as needed
 
 *"Initialized. Ready?"*
 

package/template/.claude/skills/planning/SKILL.md

@@ -7,6 +7,26 @@ description: "Break work into executable tasks with verification gates. Enforces
 
 > **Do NOT use `EnterPlanMode`.** Output -> `.forge/phases/`.
 
+## Core Principle: Vertical Slicing
+
+**Every phase and every plan MUST deliver a thin vertical slice -- a user-observable behavior reachable end-to-end (UI -> API -> data, or CLI -> core -> output).** Never decompose by horizontal layer (all models, then all APIs, then all UI). Horizontal slicing defers user-testable behavior until the last phase and amplifies integration risk.
+
+Why:
+- Each slice is testable, demoable, shippable on its own
+- Bugs surface at the seam (where layers meet) on day one, not week three
+- User can redirect direction after slice 1 instead of after the whole stack lands
+
+Apply at three levels:
+- **Roadmap (Step 5)**: phases are slices, not layers
+- **Decompose (Step 6)**: plans are slices, not layers
+- **Verify (Step 8)**: Slice Integrity gate -- hard fail on layer-only plans
+
+Exceptions (must be explicitly justified in plan frontmatter `slice_exception:`):
+- Foundational infra phase that no slice can reach yet (build setup, framework bootstrap)
+- Shared library / cross-cutting refactor with no user-facing surface
+
+If you find yourself writing a plan that only touches `src/models/`, `src/db/`, `src/schemas/`, `src/api/` (without UI/CLI counterpart), or `src/components/` (without data path) -- STOP. Merge with the slice that reaches the user, or claim an exception.
+
 ## Step 1: Resolution Gate
 
 Read `.forge/context.md` **Needs Resolution**. If unchecked `- [ ]` items:
@@ -77,11 +97,14 @@ Never write to top-level `.forge/requirements.yml` -- that path is deprecated.
 ### Case A: `roadmap.yml` missing (Full only)
 
 Create from `.forge/templates/roadmap.yml`:
-1. Group by delivery boundaries
-2. Inter-group dependencies
-3. Phases (coherent, verifiable)
+1. **Group by vertical slice, NOT by layer.** Each phase = a thin end-to-end user journey. Wrong: `m1-models`, `m2-apis`, `m3-ui`. Right: `m1-user-can-sign-up`, `m2-user-can-post`, `m3-user-can-comment`.
+2. Inter-slice dependencies (slice B builds on artifact from slice A)
+3. Each phase has a one-sentence `goal:` written as user-observable outcome ("User can X"), never as "Build Y"
 4. Every FR -> one phase, no orphans
-5. Waves: independent=1, dependent=2+
+5. Waves: independent slices=1, dependent slices=2+
+6. **Phase 1 must be demoable.** If phase 1 has no user-observable output, the roadmap is layered -- redesign.
+
+Anti-pattern detection: scan proposed phase names. Reject if any phase name contains layer-only terms without a user verb: `models`, `schema`, `database`, `api-only`, `backend-only`, `ui-only`, `frontend-only`, `infrastructure` (unless tagged as exception phase).
 
 ### Case B: `roadmap.yml` exists, current milestone already in it
 
@@ -105,16 +128,62 @@ If a sibling milestone (e.g. m50) has state + requirements but is missing from `
 
 ## Step 6: Decompose Tasks
 
-Per phase (or feature, Standard tier):
+### Step 6.1: Cross-Layer Contract Detection
+
+Before decomposing, classify whether this phase crosses a layer boundary with a *new or changing* contract. This decides single-plan vs a contract-pinned layer split. Read the project's layers from `project.yml` `layers:` (or `.forge/contracts/index.yml`; fallback: top-level source dirs).
+
+**Trigger -- all three hold:**
+1. Work touches >= 2 declared layers (e.g. engine / blocks / ui).
+2. A struct / signature / ABI field / descriptor is *produced* by one layer and *consumed* by another.
+3. That interface is *new or changing* in this phase.
+
+**Litmus (decisive):** "Would an agent building one layer in isolation have to GUESS the shape the other layer owns?" No (already specified in a durable contract) -> not cross-layer here.
+
+**Two contract tiers:**
+- **Durable** = the standing layer API. Lives in ADRs (`.forge/decisions/`) + constitution, indexed in `.forge/contracts/index.yml` (integration-point -> governing ADR). Stable + unchanged -> agents read the ADR; no per-phase artifact.
+- **Per-phase delta** = the specific new/changed shape THIS phase introduces. Pinned in `.forge/phases/m{M}-{N}-{name}/contract.md` (from `.forge/templates/contract.md`); references its governing ADR; folded back into that ADR on landing.
+
+**Classify:**
+
+| Tier | Condition | Response |
+|------|-----------|----------|
+| 0 | Trigger fails | Normal decomposition (6.2). Nothing added. |
+| 1 | Cross-layer delta, small / tightly sequential | Write `contract.md`; tag tasks `layer:`; ONE plan. No interruption. |
+| 2 | Cross-layer delta, cleanly separable, worth parallel sessions | Pin `contract.md`; split into plan-NNa (producer layer, pins contract) + plan-NNb (consumer layer, `depends_on` the contract). Ratify gate. |
+
+**Liberal detect, conservative interrupt:** classify every phase. Unsure between 1 and 2 -> default **Tier 1** (write the doc, no interruption). Escalate to 2 only when confident the parallel split pays off.
+
+**Tier-2 ratify gate** (the ONLY interruption; frame as contract-correctness, not "parallelize y/n"):
+> *"This phase changes the {integration point} contract ({governing ADR}). Delta: [summary]. plan-NNa ({producer}) pins it; plan-NNb ({consumer}) builds against it in parallel. Is this contract shape correct?"*
+
+Block the split until confirmed. Override ("keep it one plan") -> log to `state/index.yml` `desire_paths` (recurring overrides tune the threshold), fall back to Tier 1.
+
+**Integration (Tier 2):** layer plans build isolated (per-layer worktrees). The phase's final task is a **seam check** owned by the executing flow (NOT a standing agent): merge the layer branches, verify the shape the producer emits matches what the consumer built against, per `contract.md`.
+
+### Step 6.2: Task Decomposition
+
+Per phase (or feature, Standard tier). **Each plan = one vertical slice** -- except a sanctioned Tier-2 contract split (6.1), which divides one slice across producer/consumer layer plans reconciled at the seam check.
+
+#### Slice-First Decomposition
+
+Before writing any plan:
+1. List the user-observable behaviors this phase must deliver (from `requirements/m{N}.yml`)
+2. For each behavior, identify the full path: UI/CLI surface -> handler -> business logic -> persistence (only the parts that behavior needs)
+3. **One plan = one behavior end-to-end.** Plan touches every layer that behavior needs, not all of one layer.
+4. If a plan can only ship part of the path (e.g., UI without backend wired), it is NOT a slice -- restructure.
+
+Plan naming reflects the slice: `plan-01-user-signs-up.md`, not `plan-01-models.md`.
+
+#### File Layout
 
 1. `.forge/templates/plan.md` -> `.forge/phases/m{M}-{N}-{name}/plan-{NN}.md`
    - `{M}`=milestone, `{N}`=phase#, `{name}`=kebab, `{NN}`=seq
    - Ex: `.forge/phases/m3-2-providers/plan-01.md`
-2. Frontmatter: phase, plan#, wave, deps
+2. Frontmatter: phase, plan#, wave, deps, `slice_exception:` (optional, see Core Principle)
 3. must_haves:
-   - **Truths:** User-observable outcomes (3-7)
-   - **Artifacts:** Must exist, substantive not stubs
-   - **Key Links:** Connections between artifacts
+   - **Truths:** User-observable outcomes (3-7). MUST be phrased as something the user can see, click, or receive -- not "model X exists" or "table Y created".
+   - **Artifacts:** Must exist, substantive not stubs. Slice plans typically span 2-4 layers (e.g., component + handler + repo).
+   - **Key Links:** Connections between artifacts -- these prove the slice is wired, not stubbed.
 4. XML tasks (2-3/plan, 15-60 min):
 
 ```xml
@@ -144,20 +213,45 @@ Per phase (or feature, Standard tier):
 | `checkpoint:decision` | Pause for user choice between options |
 | `checkpoint:human-action` | Pause for manual action (email verification, 2FA) |
 
-### Vertical Slices (Preferred)
+### Vertical Slices (Required)
+
 ```
-Plan 01: User feature (model + API + UI)   → Wave 1
-Plan 02: Product feature (model + API + UI) → Wave 1
+Plan 01: User can sign up    (UI form + /api/signup + users table write)  → Wave 1
+Plan 02: User can log in     (UI form + /api/login + session issue)        → Wave 2 (uses table from 01)
+Plan 03: User can post note  (UI editor + /api/notes + notes table)        → Wave 2 (uses auth from 02)
 ```
-Independent plans run parallel.
 
-### Avoid Horizontal Layers
+Each plan is independently demoable. Bugs at layer seams surface in plan 01.
+
+### Horizontal Layers (Anti-Pattern -- BLOCKED)
+
 ```
-Plan 01: All models    → Wave 1
-Plan 02: All APIs      → Wave 2 (depends on 01)
-Plan 03: All UI        → Wave 3 (depends on 02)
+Plan 01: All models       → Wave 1
+Plan 02: All APIs         → Wave 2 (depends on 01)
+Plan 03: All UI           → Wave 3 (depends on 02)
 ```
-Sequential. Only when architecturally required.
+
+This decomposition is **rejected by default** at Step 8 (Slice Integrity gate). To proceed, declare `slice_exception:` in plan frontmatter with one of:
+- `infra_bootstrap` -- foundational setup with no user-reachable surface
+- `shared_library` -- cross-cutting utility used by future slices
+- `data_migration` -- one-shot schema/data change with no behavior added
+
+Anything else: restructure into slices.
+
+### Anti-Pattern Auto-Detector
+
+A plan fails Slice Integrity if ALL of:
+- `must_haves.truths` contain only artifacts/internals (e.g., "Schema migration applied", "Model class created") with no user-visible verb (see, click, receive, fail-with-error)
+- `must_haves.artifacts` paths all live under a single layer prefix (only `src/models/`, only `src/api/`, only `src/components/`)
+- No `slice_exception:` declared
+
+Detection runs in Step 8.
+
+### Contract-Driven Layer Split (Tier 2 exception)
+
+When Step 6.1 flags a **Tier-2** cross-layer contract, splitting by layer is correct -- NOT the horizontal anti-pattern above. The difference:
+- *Horizontal anti-pattern:* split by layer with no contract; each layer waits on the previous. Serializes.
+- *Contract-driven split:* plan-NNb `depends_on` the **frozen contract** (pinned by NNa up front), not NNa's implementation -> both layers build in parallel (separate sessions/worktrees), reconciled at the seam check.
 
 ## Step 7: Test Specs (Optional)
 
@@ -249,7 +343,7 @@ Decision captured once, pre-code. Does not block planning.
 
 ## Step 8: Verify Plans
 
-8 dimensions:
+9 dimensions:
 1. **Requirement Coverage** -- every req has task(s)
 2. **Task Completeness** -- files + action + verify + done
 3. **Deps** -- valid DAG, no cycles
@@ -258,6 +352,20 @@ Decision captured once, pre-code. Does not block planning.
 6. **Verification** -- must_haves trace to goal
 7. **Context** -- honors locked, excludes deferred
 8. **Spec Validity** -- valid syntax, correct paths
+9. **Slice Integrity (HARD GATE)** -- every plan delivers a vertical slice OR declares `slice_exception:`
+
+### Slice Integrity Check
+
+For each plan, FAIL if all of these hold and no `slice_exception:` is declared:
+- `must_haves.truths` lack a user-observable verb (`see`, `click`, `submit`, `receive`, `view`, `download`, `error`, `redirected`, `login`, `signup`, etc.) -- internal-only truths like "Schema applied", "Model registered", "Index built" do not satisfy
+- `must_haves.artifacts` paths cluster in a single layer (all under `models/`, all under `api/`, all under `components/`, etc.)
+- No file path crosses a layer boundary (e.g., a component plus its handler, a CLI plus its core)
+
+**Exempt:** a Tier-2 contract-split plan (Step 6.1) carries both `layer:` and `contract:` frontmatter. It is a sanctioned single-layer plan reconciled at the seam check -- treat as auto-`slice_exception` (the *phase*, not the plan, owns the vertical slice). It passes without declaring `slice_exception:`.
+
+Roadmap-level check: FAIL if phase 1 has no user-observable goal.
+
+On fail: restructure plan(s) into slices, or declare `slice_exception:` with one of `infra_bootstrap | shared_library | data_migration` and a one-line rationale. Re-verify.
 
 Issues -> fix, re-verify. Max 3 cycles.
 

package/template/.claude/skills/reviewing/SKILL.md

@@ -371,9 +371,21 @@ If the milestone being completed has `milestone.origin: {R-id}` set (promoted fr
 3. Update item: `status: resolved`, set `completed: "<ISO 8601 date>"`. Keep `promoted_to: {milestone-id}` intact for audit trail.
 4. Log in summary: *"Backlog item {R-id} → resolved (promoted milestone {id} complete)."*
 
+## Contract Landing (cross-layer phases)
+
+If the milestone's phases produced `contract.md` files (planning Step 6.1 Tier 1/2), close their lifecycle before completing the milestone. The durable contract is the ADR; the per-phase `contract.md` is a working delta that must be folded back in.
+
+1. Glob `.forge/phases/m{id}-*/contract.md`.
+2. For each contract not yet `absorbed` (Tier-2 lands at `ratified` after the executing seam check; Tier-1 lands at `proposed` — both fold the same way now that the phase is verified):
+   - Fold `delta` into its `governing_adr` — amend the ADR in `.forge/decisions/`, or supersede it (`Status: Superseded by ADR-{NNN}`) if the shape changed materially.
+   - If a **new** integration point was introduced, add it to `.forge/contracts/index.yml` `integration_points:` (id, produces, consumes, governing_adr, summary).
+   - Set the contract's `status: absorbed`. The ADR is now authoritative; `contract.md` becomes history.
+3. Any contract with no `governing_adr` set (nothing to fold into) → warn: *"Contract {integration_point} has no governing ADR — file one in `.forge/decisions/` before close, or the durable contract drifts from code."* Advisory — does not block completion.
+
 ## Phase Handoff
 
 1. Confirm report + backlog
 2. **Run promoted-milestone completion hook** (above) if `milestone.origin` set
-3. Set `current.status: complete` and `current.completed_at: "<ISO 8601 timestamp>"`
-4. *"Milestone [{name}] complete. Report: `.forge/audits/milestone-{id}-health-report.md`. {N} backlog items. `/forge` or backlog."*
+3. **Run Contract Landing** (above) for any cross-layer phases — fold ratified contracts into their ADRs
+4. Set `current.status: complete` and `current.completed_at: "<ISO 8601 timestamp>"`
+5. *"Milestone [{name}] complete. Report: `.forge/audits/milestone-{id}-health-report.md`. {N} backlog items. `/forge` or backlog."*

package/template/.forge/templates/contract.md

@@ -0,0 +1,27 @@
+# Phase Contract: {integration point}
+
+Copy to `.forge/phases/m{M}-{N}-{name}/contract.md` when planning **Step 6.1** detects a cross-layer delta (Tier 1 or 2). Pins the NEW or CHANGED interface shape the producing and consuming layers must agree on for this phase, so an agent building one layer in isolation does not have to guess the other's shape.
+
+Lifecycle: pinned by the producer plan (NNa) BEFORE the consumer plan (NNb) builds against it -> ratified at the Tier-2 gate -> folded into the governing ADR when the phase lands (`status: absorbed`). The durable contract is the ADR; this file is the working delta on top of it.
+
+---
+
+```yaml
+contract:
+  integration_point: ""        # e.g. "engine -> ui (block descriptor)"
+  governing_adr: ""            # durable contract this delta extends, e.g. "ADR-026" (see .forge/contracts/index.yml)
+  producer_layer: ""           # owns + pins the shape (plan-NNa), e.g. "engine"
+  consumer_layer: ""           # builds against it (plan-NNb), e.g. "ui"
+  status: proposed             # proposed | ratified | absorbed
+  delta: |
+    # The exact new/changed shape the consumer must NOT have to guess:
+    # struct fields, ABI fields + sizeof/layout, function signatures,
+    # enum values, units, ownership. ASCII only.
+  seam_check: ""               # how integration verifies producer output == consumer expectation,
+                               # e.g. "ui block_shape_projection_test asserts port count from descriptor"
+```
+
+## Notes
+- One contract block per cross-layer delta. A phase changing two integration points pins two blocks (or two files).
+- The consumer plan's `depends_on` points at THIS contract reaching `status: ratified`, NOT the producer plan's completion -- that is what lets the layers build in parallel.
+- On landing: amend or supersede `governing_adr` to absorb `delta`, set `status: absorbed`. The ADR is then authoritative; this file becomes history.

package/template/.forge/templates/contracts-index.yml

@@ -0,0 +1,35 @@
+# Durable cross-layer contract index
+#
+# Maps each standing integration point between layers to the ADR(s) that
+# govern it. Planning Step 6.1 reads this to (a) know an integration point
+# already has a durable contract, (b) decide whether the current phase
+# CHANGES it, (c) point producer/consumer agents at the authoritative shape.
+#
+# Durable contracts live in the ADRs themselves (.forge/decisions/). This
+# index is only the lookup. A phase that changes a contract pins a per-phase
+# delta in its contract.md, then folds it back into the governing ADR.
+#
+# Copy to .forge/contracts/index.yml and fill in for your project.
+
+# The project's architectural layers -- used by the cross-layer trigger
+# (Step 6.1 condition 1: "work touches >= 2 declared layers").
+layers:
+  - name: ""                   # e.g. "engine"
+    path: ""                   # e.g. "engine/"
+  # - name: "blocks"
+  #   path: "blocks/"
+  # - name: "ui"
+  #   path: "ui/"
+
+# Standing integration points and their governing ADR(s).
+integration_points:
+  - id: ""                     # e.g. "engine<->block"
+    produces: ""               # producer layer, e.g. "engine"
+    consumes: ""               # consumer layer, e.g. "blocks"
+    governing_adr: []          # e.g. ["ADR-001"]
+    summary: ""                # one line: what the contract covers
+  # - id: "engine->ui"
+  #   produces: "engine"
+  #   consumes: "ui"
+  #   governing_adr: ["ADR-026"]
+  #   summary: "Block descriptor: UI projects ports/params/layout from the engine descriptor"

package/template/.forge/templates/plan.md

@@ -16,20 +16,32 @@ type: execute                        # execute | tdd
 wave: 1                              # Execution wave (1 = no dependencies)
 depends_on: []                       # Plan IDs that must complete first
 autonomous: true                     # false if contains checkpoints
+layer: ""                            # name from project.yml layers[], or "" -- set by planning Step 6.1 cross-layer split (Tier 1/2)
+contract: ""                         # path to this phase's contract.md (cross-layer delta this plan pins/consumes), if any
+
+# Vertical slice declaration. A plan delivers a thin end-to-end user behavior
+# (UI -> API -> data, or CLI -> core -> output). Plans that touch only ONE layer
+# are rejected by the planning Slice Integrity gate unless slice_exception is set.
+slice_exception: null                # null | infra_bootstrap | shared_library | data_migration
+slice_exception_rationale: ""        # Required if slice_exception != null. One line.
 
 must_haves:
-  truths:                            # Observable from user perspective when plan is done
-    - ""                             # e.g., "User can see their profile page"
-    - ""                             # e.g., "API returns user data as JSON"
-  artifacts:                         # Files that must exist and be substantive (not stubs)
-    - path: ""                       # e.g., "src/components/Profile.tsx"
-      provides: ""                   # e.g., "User profile display with avatar and bio"
+  truths:                            # USER-observable when plan is done. Must contain a user verb
+                                     # (see, click, submit, receive, view, download, error, redirect).
+                                     # Internal-only truths like "Schema applied" do NOT satisfy.
+    - ""                             # e.g., "User submits signup form and lands on dashboard"
+    - ""                             # e.g., "Invalid email shows inline 'must be a valid email' error"
+  artifacts:                         # Files that must exist and be substantive (not stubs).
+                                     # Slice plans typically span 2-4 layers — paths should cross
+                                     # boundaries (component + handler + repo), not cluster in one dir.
+    - path: ""                       # e.g., "src/components/SignupForm.tsx"
+      provides: ""                   # e.g., "Signup form with email + password fields"
       min_lines: 30                  # Stub detection threshold
-  key_links:                         # Critical connections between artifacts
-    - from: ""                       # e.g., "src/components/Profile.tsx"
-      to: ""                         # e.g., "/api/users/[id]"
-      via: ""                        # e.g., "fetch in useEffect"
-      pattern: ""                    # e.g., "fetch.*api/users"
+  key_links:                         # Connections between layers — these prove the slice is wired
+    - from: ""                       # e.g., "src/components/SignupForm.tsx"
+      to: ""                         # e.g., "/api/signup"
+      via: ""                        # e.g., "fetch on submit"
+      pattern: ""                    # e.g., "fetch.*api/signup"
 ```
 
 ## Tasks

package/template/.forge/templates/project.yml

@@ -14,6 +14,12 @@ tech_stack:
   testing: ""                       # e.g., Vitest, Jest, Pytest
   other: []                         # Additional key dependencies
 
+layers: []                             # Architectural layers — enables cross-layer contract detection (planning Step 6.1).
+                                       # Populated during init (brownfield: producer/consumer source dirs; greenfield: asked).
+                                       # Each entry: {name, path}. Empty/absent = single-layer project, detection no-ops.
+                                       # e.g. [{name: engine, path: src/engine/}, {name: ui, path: src/ui/}]
+                                       # Durable integration points + governing ADRs live in .forge/contracts/index.yml.
+
 interface: [none]                      # Surfaces this project exposes: browser | cli | api | desktop | native-apple | none
                                        # Array — e.g. [browser, api] for full-stack projects
 

package/template/.forge/templates/roadmap.yml

@@ -1,6 +1,16 @@
 # Forge Roadmap Template
 # Copy to .forge/roadmap.yml and customize.
-# Phases are delivery boundaries — coherent, verifiable capabilities.
+#
+# Phases are VERTICAL SLICES — thin end-to-end user journeys shippable on their own.
+# NOT horizontal layers (do NOT carve into "all models" / "all APIs" / "all UI" phases).
+#
+# Right:  m1-user-can-sign-up, m2-user-can-post, m3-user-can-comment
+# Wrong:  m1-models, m2-apis, m3-ui
+#
+# Each phase's `goal:` must read as a user-observable outcome ("User can X"),
+# never as "Build Y". Phase 1 must be demoable. The planning skill's
+# Slice Integrity gate will reject layered roadmaps unless a `slice_exception:`
+# is declared on the plan (infra_bootstrap | shared_library | data_migration).
 
 roadmap:
   # Milestones group phases into concurrent work streams.
@@ -16,13 +26,15 @@ roadmap:
   # Example: m1-1-foundation/, m1-2-auth/, m2-1-dashboard/
   phases:
     - id: 1
-      name: ""                       # e.g., "Foundation & Architecture"
-      goal: ""                       # Outcome, not task. "Users can X" not "Build Y"
-      requirements: []               # List of FR-IDs this phase delivers
+      name: ""                       # Vertical slice name, e.g., "User can sign up"
+      goal: ""                       # User-observable outcome. "User can X". Never "Build Y".
+      slice_exception: null          # null | infra_bootstrap | shared_library | data_migration
+                                     # Only set if this phase legitimately has no user-facing surface.
+      requirements: []               # List of FR-IDs this phase delivers (end-to-end)
       dependencies: []               # Phase IDs that must complete first
-      success_criteria:              # Observable truths when phase is done
-        - ""                         # e.g., "User can see the landing page"
-        - ""                         # e.g., "API returns valid JSON for /users"
+      success_criteria:              # User-observable truths when phase is done
+        - ""                         # e.g., "User submits signup form and lands on dashboard"
+        - ""                         # e.g., "Invalid email shows inline error"
       estimated_hours: null
       status: pending                # pending | researching | planning | executing | verifying | deferred | complete
 

package/template/CLAUDE.md

@@ -60,6 +60,9 @@ Auto-detects complexity. Override: "Use Quick/Standard/Full tier."
 | Systematic debugging | `debugging` | When stuck |
 | Upgrade Forge files | `upgrading` | On-demand |
 | Cross-session memory | `beads-integration` | When Beads installed |
+| Multi-agent orchestration (experimental) | `orchestrating` | Full (opt-in) |
+
+> Experimental skills require opt-in install — see `packages/create-forge/experimental/m10/README.md`.
 
 ## Context Engineering
 

package/template/.claude/hooks/forge-claim-check-doctor.sh

@@ -1,37 +0,0 @@
-#!/usr/bin/env bash
-# Forge claim-check hook prerequisites probe. Informational only — always exit 0.
-# Run manually or via install procedure to confirm bash/jq/sqlite3/timeout availability.
-
-set -uo pipefail
-
-check() {
-  local name=$1 cmd=$2 version_flag=${3:---version}
-  if command -v "$cmd" >/dev/null 2>&1; then
-    local ver
-    ver=$("$cmd" "$version_flag" 2>&1 | head -1)
-    printf '  ✓ %-10s %s\n' "$name" "$ver"
-  else
-    printf '  ✗ %-10s MISSING\n' "$name"
-  fi
-}
-
-echo "Forge claim-check hook — prerequisites"
-echo
-
-check "bash"     "bash"     "--version"
-check "jq"       "jq"       "--version"
-check "sqlite3"  "sqlite3"  "--version"
-
-if command -v timeout >/dev/null 2>&1; then
-  printf '  ✓ %-10s %s\n' "timeout" "$(timeout --version 2>&1 | head -1)"
-elif command -v gtimeout >/dev/null 2>&1; then
-  printf '  ✓ %-10s (gtimeout) %s\n' "timeout" "$(gtimeout --version 2>&1 | head -1)"
-else
-  printf '  ✗ %-10s MISSING (optional — install coreutils for bounded queries)\n' "timeout"
-fi
-
-echo
-echo "DB lookup path: ${FORGE_CLAIMS_DB:-${CLAUDE_PROJECT_DIR:-$PWD}/.forge/.mcp-server/claims.db}"
-echo "Session id:     ${CLAUDE_SESSION_ID:-<unset — hook will fail-open>}"
-
-exit 0

package/template/.claude/hooks/forge-claim-check.sh

@@ -1,96 +0,0 @@
-#!/usr/bin/env bash
-# Forge PreToolUse hook — cross-session file-claim collision detector.
-#
-# Contract:
-#   stdin: Claude Code PreToolUse JSON payload
-#   exit 0 = allow (no claim, own claim, no DB, no session context, unknown schema)
-#   exit 2 = deny (cross-session claim active, or any internal error — fail-closed)
-#
-# Defense-in-depth: ERR trap converts ANY unexpected failure into an exit-2 deny.
-# Never exit 1 — Claude Code treats exit 1 as soft warning; we want hard block on error.
-
-set -euo pipefail
-
-deny() {
-  echo "[forge-hook] $*" >&2
-  exit 2
-}
-
-trap 'deny "internal error at line $LINENO — denying for safety (fail-closed)"' ERR
-
-PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PWD}"
-DB="${FORGE_CLAIMS_DB:-$PROJECT_DIR/.forge/.mcp-server/claims.db}"
-SESSION_ID="${CLAUDE_SESSION_ID:-}"
-
-# Detect timeout wrapper (macOS lacks GNU `timeout` unless coreutils installed → `gtimeout`).
-if command -v timeout >/dev/null 2>&1; then
-  TIMEOUT_CMD=(timeout 4)
-elif command -v gtimeout >/dev/null 2>&1; then
-  TIMEOUT_CMD=(gtimeout 4)
-else
-  TIMEOUT_CMD=()  # no wrapper — sqlite call runs unbounded; busy_timeout in DB still applies
-fi
-
-PAYLOAD=$(cat)
-
-# Normalize across known path fields:
-#   Edit / Write           → tool_input.file_path
-#   NotebookEdit           → tool_input.notebook_path   (validated in spike — see milestone-10-validation.md §2)
-#   MultiEdit              → tool_input.file_path       (single file, multiple edits; per docs)
-#   Future / unknown tools → tool_input.path            (defensive)
-# jq emits each matching path on its own line. Empty output = no path field present.
-FILES=$(printf '%s' "$PAYLOAD" | jq -r '
-  [ .tool_input.file_path?
-  , .tool_input.notebook_path?
-  , .tool_input.path?
-  , ( .tool_input.edits? // [] | .[]?.file_path? )
-  ] | map(select(. != null and . != "")) | unique | .[]
-')
-
-if [ -z "$FILES" ]; then
-  # No recognized path field — unknown schema. Allow (do not deny on schema drift).
-  exit 0
-fi
-
-# No DB = MCP server has never run in this repo (fresh-repo case). Fail-open only here.
-if [ ! -f "$DB" ]; then
-  exit 0
-fi
-
-if [ -z "$SESSION_ID" ]; then
-  # No session context — single-agent or hook invoked outside Claude Code. Allow.
-  echo "[forge-hook] CLAUDE_SESSION_ID unset — allowing (single-agent mode)" >&2
-  exit 0
-fi
-
-# Resolve each path to absolute (matches what MCP server stores via path.resolve).
-abspath() {
-  case "$1" in
-    /*) printf '%s' "$1" ;;
-    *)  printf '%s/%s' "$PROJECT_DIR" "$1" ;;
-  esac
-}
-
-while IFS= read -r raw; do
-  [ -z "$raw" ] && continue
-  file=$(abspath "$raw")
-
-  # Parameterized query via .param — avoids quoting injection on path strings.
-  result=$("${TIMEOUT_CMD[@]+"${TIMEOUT_CMD[@]}"}" sqlite3 -batch "$DB" \
-    ".param set :fp '$file'" \
-    "SELECT session_id || '|' || expires_at FROM claims WHERE file_path = :fp AND expires_at > strftime('%s','now') LIMIT 1;")
-
-  [ -z "$result" ] && continue
-
-  owner="${result%%|*}"
-  expires_at="${result##*|}"
-
-  if [ "$owner" = "$SESSION_ID" ]; then
-    continue  # own claim
-  fi
-
-  expires_human=$(date -r "$expires_at" "+%Y-%m-%d %H:%M:%S %Z" 2>/dev/null || echo "epoch:$expires_at")
-  deny "Edit denied: $file claimed by session $owner until $expires_human. Call forge_release_claims in that session, or wait."
-done <<< "$FILES"
-
-exit 0

package/template/.claude/skills/orchestrating/SKILL.md

@@ -1,135 +0,0 @@
----
-name: orchestrating
-description: "[Experimental — M10] Owns multi-agent session lifecycle. Bootstrap, worktree create, claim+merge coordination, teardown. Refuses worktree mode on incompatible repos and falls back to single-agent."
----
-
-# Orchestrating
-
-Multi-agent session lifecycle. Worktree isolation + MCP-coordinated claims + merge queue. Experimental — opt-in per ADR-001. Refuses on incompatible repos, falls back to single-agent.
-
-## When to use
-
-- User explicitly invokes multi-agent mode (`/forge` argument selects multi-agent, or direct skill invocation).
-- `executing` skill at Full tier with ≥2 concurrent-eligible phases routes through this skill.
-
-Skip on Quick tier, single-phase work, or when bootstrap checks fail.
-
-## Step 1: Bootstrap
-
-Run all checks in `bootstrap-checks.md`:
-
-1. Git version ≥ 2.48
-2. LFS version ≥ 3.6 (skip if not installed)
-3. No submodules
-4. `core.hooksPath` empty or resolves inside worktree
-5. `git hook run pre-commit` smoke test in fresh worktree
-
-**Any check fails** → log reason, write `lifecycle.worktree_mode: refused` + `lifecycle.refused_reason` into active milestone state, emit fallback message (see `bootstrap-checks.md`), return to caller. Caller continues single-agent.
-
-## Step 2: Session ID + worktree
-
-```bash
-session_id=$(uuidgen | cut -c1-8)
-git worktree prune
-git worktree add -b forge/${session_id} --lock --reason "forge session" ../forge-worktrees/${session_id} main
-( cd ../forge-worktrees/${session_id} && git hook run pre-commit || true )
-```
-
-Verify worktree dir exists, branch locked. On failure → cleanup partial state, refuse mode.
-
-## Step 3: State update
-
-Write into `.forge/state/milestone-{id}.yml`:
-
-```yaml
-lifecycle:
-  session_id: "{session_id}"
-  worktree_path: "../forge-worktrees/{session_id}"
-  worktree_branch: "forge/{session_id}"
-  worktree_mode: "active"
-  started_at: "{ISO8601}"
-```
-
-Update `state/index.yml` milestone `last_updated`.
-
-## Step 4: Hand back
-
-Return control to caller (typically `executing`). All subsequent work runs inside `../forge-worktrees/{session_id}`. Caller honors claim convention.
-
-### Claim convention (executing-skill contract)
-
-Before any `Edit`, `Write`, `MultiEdit`, or `NotebookEdit` on a file outside `.forge/state/milestone-{own_id}.yml`:
-
-1. Call `forge_claim_files` with `{ session_id, files: [...], ttl_seconds: 900 }`.
-2. On `granted` → proceed with edit.
-3. On `conflict: { holder_session, files: [...] }` → surface holder + files to user. Options:
-   - **wait** → poll `forge_claim_status` until released or TTL expiry.
-   - **skip** → drop the conflicted file from the task scope, continue with rest.
-   - **steal** → only if holder session is provably dead (PreToolUse hook validates). Otherwise refused.
-4. After edit batch → claim auto-extends on continued use; explicit `forge_release_claims` on plan-complete.
-
-PreToolUse hook (installed by plan-03) enforces this — uncaught violations block at hook level, not skill level.
-
-## Step 5: Teardown
-
-Triggered when caller signals work complete OR user requests teardown.
-
-```
-forge_queue_commit(branch=forge/{session_id}, base_sha={merge_base})
-```
-
-Branch on response status:
-
-- **`merged`** → `forge_release_claims(session_id)` → `git worktree remove --force ../forge-worktrees/{session_id}` → `git branch -d forge/{session_id}` → clear `lifecycle.*` (set `worktree_mode: complete`, retain `session_id` for audit).
-- **`conflict`** → invoke `Skill(debugging)` with payload `{ conflicted_files, base_sha, messages, branch }`. Teardown blocks until debugging signals resolution (re-invoke teardown after fix).
-- **`stale_base`** → caller rebases worktree branch onto `current_main_sha` from response, retries `forge_queue_commit`. Max 3 retries → escalate to conflict path.
-
-## Step 6: Crash recovery (next session start)
-
-If no clean teardown happened previously:
-
-1. `git worktree prune` — drops stale admin dirs.
-2. `git branch --list 'forge/*'` — for each branch with no live worktree, prompt user:
-   - **resume** → re-attach: `git worktree add ../forge-worktrees/{id} forge/{id}` and restore lifecycle state.
-   - **delete** → `git branch -D forge/{id}`.
-3. MCP server startup handles pidfile takeover + claim TTL expiry independently (see ADR-003).
-
-## Failure modes & operator notes
-
-- **MCP server absent** — bootstrap check 5 (hook smoke) will not detect this. Skill detects on first `forge_claim_files` call: error `MCP_SERVER_UNAVAILABLE` → write `lifecycle.worktree_mode: degraded`, warn user, continue without claim coordination. Hard isolation (worktree) still active; coordination is downgraded to best-effort.
-- **Disk full during worktree add** — `git worktree add` will error. Cleanup any partial `../forge-worktrees/{session_id}/` dir, refuse mode, fall back.
-- **Concurrent orchestrating invocations** — second invocation reads first's `lifecycle.session_id` in state. If present and `worktree_mode: active` → refuse (one orchestration per milestone). Use a separate milestone for parallel orchestrated work.
-- **Worktree path collision** — UUIDv4 short (8 chars) collision negligible at <100 concurrent sessions. If `../forge-worktrees/{id}/` already exists → regenerate session_id, retry up to 3 times.
-
-## Example: clean session
-
-```
-user: /forge multi-agent
-forge → orchestrating
-orchestrating: bootstrap OK → session_id=a1b2c3d4 → worktree created → state written
-orchestrating → executing (working dir: ../forge-worktrees/a1b2c3d4)
-executing: claim files → edit → commit (× N tasks)
-executing → verifying → reviewing (all inside worktree)
-reviewing → orchestrating (teardown)
-orchestrating: forge_queue_commit → merged → release claims → remove worktree → delete branch
-done.
-```
-
-## Example: conflict path
-
-```
-orchestrating: forge_queue_commit → conflict { files: [src/auth.ts] }
-orchestrating → debugging { conflicted_files, base_sha, branch }
-debugging: user resolves → signal resolved
-orchestrating: retry forge_queue_commit → merged → cleanup
-```
-
-## References
-
-- ADR-001 — experimental track / opt-in carve-out
-- ADR-002 — worktrees as isolation substrate
-- ADR-003 — MCP server + per-repo SQLite
-- ADR-004 — merge queue (forge_queue_commit status semantics)
-- ADR-005 — session lifecycle (this skill realizes it)
-- `.forge/research/milestone-10.md` — spike findings
-- `bootstrap-checks.md` — bootstrap check matrix + fallback

package/template/.claude/skills/orchestrating/bootstrap-checks.md

@@ -1,48 +0,0 @@
-# Bootstrap Checks
-
-Run before worktree creation. Any failure → refuse worktree mode, fall back to single-agent.
-
-| Check | Command | Pass criterion | Fail action | Reason |
-|-------|---------|----------------|-------------|--------|
-| Git version | `git --version` | major.minor ≥ 2.48 | refuse worktree mode | Known worktree bugs < 2.48 (admin-dir leaks, prune races) |
-| LFS version | `git lfs version` (skip if not installed) | ≥ 3.6 OR not installed | refuse worktree mode | Known worktree-locking bugs < 3.6 |
-| Submodule scan | `git submodule status` | empty output | refuse worktree mode | Submodules officially "not recommended" in worktrees (git docs) |
-| `core.hooksPath` | `git config core.hooksPath` | empty OR path resolves inside worktree | refuse worktree mode | Husky/lefthook silent-skip risk when path points outside worktree |
-| Hook smoke test | `git hook run pre-commit` in fresh worktree | exit 0 OR matches main-repo exit code | refuse worktree mode | Confirms hook plumbing actually fires inside worktree |
-
-## Fallback message
-
-On any check failure, emit verbatim to user:
-
-```
-M10 worktree mode unavailable: <reason>. Continuing in single-agent mode. See ADR-005 for compatibility matrix.
-```
-
-Replace `<reason>` with the failing check name + observed value (e.g., "Git version 2.45.1 < required 2.48").
-
-## State write on refusal
-
-```yaml
-lifecycle:
-  worktree_mode: refused
-  refused_reason: "<check name>: <observed>"
-  refused_at: "{ISO8601}"
-```
-
-## Check execution order
-
-Run checks 1→5 in order. First failure halts the sequence — no point running hook smoke if Git itself is too old. Record the failing check name + observed value as `refused_reason` so the user knows exactly what to fix.
-
-## Remediation hints
-
-| Failing check | User remediation |
-|---------------|------------------|
-| Git version | Upgrade Git to ≥ 2.48 (Homebrew: `brew upgrade git`; apt: backports or PPA) |
-| LFS version | Upgrade Git LFS to ≥ 3.6 OR uninstall if not actually used |
-| Submodule scan | Convert submodules to subtrees or vendored copies; M10 cannot coexist with submodules per upstream git guidance |
-| `core.hooksPath` | Either unset (`git config --unset core.hooksPath`) or move hook dir inside repo tree so it resolves under each worktree |
-| Hook smoke test | Inspect failing hook output; common cause is hook script assuming `$PWD` is main repo root — fix to use `git rev-parse --show-toplevel` |
-
-## Re-running checks
-
-Bootstrap is idempotent and cheap (~200ms total). Skill re-runs on every session start; users do not invoke directly. If a check transiently fails (e.g., LFS not yet installed during initial setup), simply restart the orchestration entry.