forge-orkes 0.41.0 → 0.44.0

package/template/.claude/settings.json

@@ -23,6 +23,39 @@
       "max_retries": 2
     }
   },
+  "permissions": {
+    "deny": [
+      "Read(./.env)",
+      "Read(./.env.*)",
+      "Read(**/.env)",
+      "Read(**/.env.*)",
+      "Read(**/secrets/**)",
+      "Read(**/.secrets/**)",
+      "Read(**/*.pem)",
+      "Read(**/*.key)",
+      "Read(**/*.p12)",
+      "Read(**/*.pfx)",
+      "Read(**/id_rsa)",
+      "Read(**/id_ed25519)",
+      "Read(**/credentials.json)",
+      "Read(**/auth.json)",
+      "Read(**/.composer-auth.json)",
+      "Read(**/.npmrc)",
+      "Read(**/.pypirc)",
+      "Edit(**/.env)",
+      "Edit(**/.env.*)",
+      "Edit(**/secrets/**)",
+      "Edit(**/.secrets/**)",
+      "Edit(**/*.pem)",
+      "Edit(**/*.key)",
+      "Write(**/.env)",
+      "Write(**/.env.*)",
+      "Write(**/secrets/**)",
+      "Write(**/.secrets/**)",
+      "Write(**/*.pem)",
+      "Write(**/*.key)"
+    ]
+  },
   "hooks": {
     "PostToolUse": [
       {
@@ -43,6 +76,15 @@
             "command": "mkdir -p .forge && echo \"$TOOL_INPUT\" > .forge/.active-skill"
           }
         ]
+      },
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/format-on-save.sh\""
+          }
+        ]
       }
     ],
     "PreToolUse": [
@@ -51,7 +93,24 @@
         "hooks": [
           {
             "type": "command",
-            "command": "if [ ! -f \"$(git rev-parse --show-toplevel 2>/dev/null)/.forge/.active-skill\" ]; then echo \"[Forge] No active skill. Invoke /forge or /quick-tasking before editing code. To bypass: touch .forge/.active-skill\" >&2; exit 2; fi"
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/forge-active-skill-guard.sh\""
+          }
+        ]
+      },
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/protect-files.sh\""
+          },
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/warn-large-files.sh\""
+          },
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/scan-secrets.sh\""
           }
         ]
       },
@@ -63,6 +122,15 @@
             "prompt": "Verify the git commit message follows Forge format: {type}({scope}): {description}. Types allowed: feat, fix, test, refactor, chore, docs. If the message doesn't match, suggest the correct format."
           }
         ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/block-dangerous-commands.sh\""
+          }
+        ]
       }
     ]
   }

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

@@ -28,6 +28,8 @@ When an architectural decision conflicts with vertical slicing (e.g., a framewor
 
 ## Architecture Decision Record (ADR)
 
+**Reserve the ADR number first (cross-worktree safety — blocking gate).** Before authoring a new ADR, allocate its number via the **ID Reservation Protocol** (FORGE.md). **Do not create the ADR file until its reservation is appended and committed** — the reserve step is mandatory, not advisory. The next number is `max(highest `kind: adr` in `.forge/reservations.yml`, highest `ADR-NNN` in `.forge/decisions/`) + 1; append one `{kind: adr, id, milestone, reserved_at, summary}` entry to `.forge/reservations.yml`, **commit + push it**, *then* write the ADR file. Bare "scan `decisions/` for the highest + increment" only sees committed state, so two worktrees architecting in parallel both pick the same `ADR-NNN` and collide silently until merge (a multi-file renumber). See FORGE.md → **ID Reservation Protocol** for the full rule. No `reservations.yml` yet ⇒ scan as before and the first reservation creates it (lazy migration).
+
 Record every significant decision in `.forge/decisions/`:
 
 ```markdown

package/template/.claude/skills/chief-of-staff/SKILL.md

@@ -78,29 +78,25 @@ every field has one source and coverage is computed into the artifact. Run the
 rollup at the **start of Show and Sync**, and after any Start/Resume/Pause/Close
 edit to a stream file.
 
-Procedure (deterministic + idempotent — never hand-edit `active.yml`):
-
-1. Glob `.forge/streams/{stream}.yml`. Each → a row: `coordination` = the file's
-   `status`; plus goal, runtime (branch/worktree), ownership summary,
-   `merge_readiness` (from `merge.readiness`), `blocked_by`, `next_action`.
-2. For a stream with `stream.milestone: m-{id}`, read `phase` + activity from
-   `.forge/state/milestone-{id}.yml` (`current.status`, `last_updated`) — do not
-   store workflow phase in the stream file. Linked milestone `deferred`/`complete`/
-   absent → `phase` reflects that (and surface it: a deferred milestone's stream
-   should likely pause; offer it).
-3. Glob active milestones (`index.yml` `status: active`). Any with **no** stream
-   file → emit a derived `stream: implicit` row (phase from the milestone, no
-   coordination) so coverage is guaranteed — an active milestone is never silently
-   missing. Offer to materialize a stream file if it needs coordination (never
-   auto-create).
-4. Derive `merge_queue:` — one entry per stream with `merge.readiness: ready`.
-5. Write `active.yml` (`version`, `updated_at`, derived `streams:` sorted by id,
-   derived `merge_queue:`). No hand-edited keys.
+Procedure: run the **Stream Rollup** exactly as defined in FORGE.md → Stream
+Rollup — the deterministic join + write (glob stream files, derive each row's
+`coordination`/`merge_readiness`/`blocked_by`/`next_action`, read `phase` from the
+linked milestone, emit `stream: implicit` coverage rows, derive `merge_queue` from
+`merge.readiness: ready`, write `active.yml`) is **single-sourced there**. Never
+hand-edit `active.yml`. Beyond that deterministic write, the Chief adds two
+**interactive** steps the boot-time rollup omits:
+
+- **Deferred/complete linked milestone** → when a stream's `stream.milestone`
+  points at a `deferred`/`complete` milestone, surface it: the stream should
+  likely pause — offer it.
+- **Implicit row needs coordination** → when an active milestone has no stream
+  file (the rollup emits a `stream: implicit` row for coverage), offer to
+  materialize a stream file for it. **Never auto-create.**
 
 Note: invoked directly, `/chief-of-staff` does not run `forge`'s milestone Rollup,
-so `index.yml` may be slightly stale; read it as-is for step 3 and suggest a
-`/forge` pass if it looks off. The Chief writes `active.yml` (derived class); it
-never writes `index.yml` or any milestone file.
+so `index.yml` may be slightly stale; read it as-is when deriving implicit-row
+coverage and suggest a `/forge` pass if it looks off. The Chief writes `active.yml`
+(derived class); it never writes `index.yml` or any milestone file.
 
 ## Start Stream Flow
 
@@ -168,11 +164,12 @@ existing M10 state.
      pre-convention `git worktree add`; `git worktree move` it and update the
      record."* Adopt the recorded path as-is regardless (advisory, never a block;
      honors `orchestration.worktree_root`).
+   - **Submodules:** if the worktree was created manually (`git worktree add`, not via `orchestrating`) and the repo has submodules, they are empty until inited. Don't build from it blind — `executing`'s Workspace Prerequisites step inits them before the first build; surface this when handing the stream off so it isn't discovered as a mid-build failure.
    - `runtime.worker_sessions` with the M10 session / claim ids
    - `ownership.owned_surfaces`, `shared_surfaces`, and `read_only_surfaces`
      as empty lists if unknown
    - `blockers` from milestone blockers or degraded/refused notes
-   - `context.milestone` pointing at `.forge/state/milestone-{id}.yml`
+   - `stream.milestone: "m-{id}"` — the rollup join key (phase derives from the linked milestone's state); this is the same link step 8 confirms
 7. Populate the stream brief with:
    - current milestone/phase/status
    - worktree path and branch
@@ -242,11 +239,24 @@ Compare all `active`, `delegated`, and `ready` streams:
   reservation, contract, or explicit merge order
 - overlapping `shared_surfaces` requires a named contract owner
 - overlapping `read_only_surfaces` is safe
+- two streams holding the same `runtime.lease.resource` is an exclusive-resource conflict — serialize (see **Exclusive Resource Leases**)
 - missing ownership is a conflict until clarified
 
 Record conflicts in both the registry and the affected stream files. Do not let
 workers resolve cross-stream conflicts directly.
 
+## Exclusive Resource Leases
+
+Surface conflict detection covers **files**. It does not cover a **single exclusive non-file resource** that two concurrent streams both need — a physical test device, a hardware port, a singleton bundle ID, a shared local DB/emulator. Two streams each `xcrun devicectl device install` to the same device, or deploy the same bundle ID, and each **clobbers the other's build**: a stream's device-verify gate opens the app and finds a *sibling's* build, the block under test absent (forge#15, canvaz m-AW01). Files don't collide here, so the surface check passes — and the clobber only shows up at device UAT.
+
+Two complementary remedies; prefer (1), fall back to (2):
+
+1. **Isolate the resource per stream (no lease needed).** When the resource *can* be made per-stream, do that instead of serializing. The canonical case: derive a **per-worktree bundle-ID suffix** from the worktree anchor (`co.example.app` → `co.example.app.m-AW01`) so every stream's build coexists on one device. This is **project-level config** (the iOS/CMake build reads the anchor from `git branch --show-current`), not Forge core — record it as a constitution/`project.yml` convention for the stack. Isolated → the streams never contend; skip the lease.
+
+2. **Lease the resource (when it genuinely can't be split).** Declare exclusive resources in `project.yml` (`orchestration.exclusive_resources: [ios_device, …]`). A stream that needs one records a lease in **its own** stream file — `runtime.lease: {resource, acquired_at, operation}` (single-owner-mutable, the stream's driver writes it; no cross-stream contention). The owning skill (e.g. `verifying`'s device-verify gate) **acquires before** the deploy-and-verify, **releases after** (clears the field). The Chief detects double-claims the same way it detects surface overlap: scan stream files for two holding the same `runtime.lease.resource` → **serialize** them (one waits, or skips its device gate until the resource frees). Until a stream releases, siblings needing that resource queue.
+
+Add the lease scan to **Detect Conflicts** (above) and the **Merge Cadence Check**: a held lease is a soft block on the holder's siblings' device gates, never on merge.
+
 ## Merge Safe Flow
 
 Use "merge safe" to identify streams that can land:
@@ -282,10 +292,11 @@ merge/rebase), and **cross-stream merge order**. A checkpoint stream that is
 cleanly auto-publishing needs no nudge here.
 
 1. **Ready-to-merge surfacing.** From `active.yml`, collect streams with
-   `status: ready` (and any `merge_queue` entries). For each, run the Merge Safe
-   Flow conditions. Unblocked + no conflicts → list under **Ready to merge** with
-   a one-line *"ready — integrate now"* and, if known, how long it has been ready
-   (from the stream's `last_sync` / brief date). Add/refresh its `merge_queue`
+   `coordination: ready` (the derived-row coordination field) plus any
+   `merge_queue` entries (derived from `merge.readiness: ready`). For each, run the
+   Merge Safe Flow conditions. Unblocked + no conflicts → list under **Ready to
+   merge** with a one-line *"ready — integrate now"* and, if known, how long it has
+   been ready (from the stream's `stream.updated_at` / brief date). Add/refresh its `merge_queue`
    entry (`status: waiting`). Blocked → list the named reason instead.
 2. **Idle-ready nudge.** A stream that has sat `ready` across **multiple Show/Sync
    passes** or whose branch is mergeable but untouched is the cadence smell.

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

@@ -10,9 +10,25 @@ description: "Build to plan with atomic commits, deviation rules, and context en
 - [ ] Context.md locked decisions noted
 - [ ] Constitution.md gates satisfied
 - [ ] Milestone state updated to `status: executing`
+- [ ] Workspace prerequisites met — submodules populated (see below)
 - [ ] Baseline snapshot captured (see below)
 - [ ] Plan anchors re-derived against HEAD (see below)
 
+## Workspace Prerequisites
+
+Run **first, before the baseline snapshot** — a missing prerequisite makes the baseline's build/test commands fail for reasons that have nothing to do with the plan.
+
+**Submodules.** A freshly-created worktree carries submodule gitlinks but leaves the directories **empty** until `git submodule update --init` runs — the first build then fails partway through with a confusing error (a missing third-party target, an empty `external/` dir), not an obvious "submodules uninitialised". `orchestrating` inits submodules when *it* creates the worktree, but a worktree from any other origin (a manual `git worktree add`, a `chief-of-staff` stream, a fresh clone) does not. So assert it here, regardless of how the workspace was created:
+
+```bash
+# No-op when the repo has no submodules; a fast checkout when objects are already in the shared common git dir.
+if [ -f .gitmodules ] && git submodule status | grep -q '^-'; then
+  git submodule update --init --recursive
+fi
+```
+
+Surface the init if it ran (*"populated N uninitialised submodule(s) before baseline"*). A `+`/`U` line (divergent/conflicted submodule) is **not** an init case — STOP under Rule 4; it signals real submodule movement. (Desire-path: canvaz m-TIDES01 — empty `external/JUCE` failed the first CMake configure mid-task.)
+
 ## Baseline Snapshot
 
 Run **before the first task begins**. Makes failure causality mechanical — no self-assessment.

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

@@ -45,7 +45,14 @@ git worktree list --porcelain 2>/dev/null \
 - `behind > 0` and the worktree has **no divergent local commits** (`git rev-list --count main..HEAD` is 0) → **fast-forward automatically**: `git merge --ff-only main`. A fast-forward is conflict-free by definition, so do it without asking; report *"pulled {N} commit(s) from main (checkpoint integration)."* Mark the sha seen.
 - `behind > 0` **and** the worktree has diverged → **surface, do not auto-rebase**: *"main advanced on {surfaces} since this worktree branched — rebase onto main? (`git rebase main`)"* — rebase can conflict; the operator decides.
 
-Cross-machine note: the flag file is machine-local, so a worktree on another laptop relies on the opt-in `forge.worktree_rebase_check` / a periodic fetch instead — eventual, not instant.
+**Integration flag check (consumer — main checkout).** When `in_main_checkout: true`, the same flag tells the operator's **canonical** checkout that a checkpoint pushed work to `origin/main` it hasn't pulled — the other half of the producer's strand-safe publish (FORGE.md → Stream Integration Checkpoints; forge#13). Without this, local main sits behind origin after every checkpoint and the next local commit silently diverges it. Same event-driven gate:
+
+- Read `.git/forge/integration-pending`. Absent, or its sha already seen by this checkout → **skip** (no fetch). No flag → no work.
+- Flag set with an unseen sha → `git fetch origin main` (if a remote), then `behind=$(git rev-list --count main..origin/main 2>/dev/null)` (local `main` vs the freshly-fetched `origin/main`). `behind` is 0 → mark seen, skip.
+- `behind > 0` and local main has **not** diverged (`git rev-list --count origin/main..main` is 0) → **fast-forward automatically** (the producer's strand guard guarantees this is a true ff): `git merge --ff-only origin/main` on `main`. Report *"fast-forwarded local main +{N} from origin (checkpoint integration)."* Mark seen.
+- `behind > 0` **and** local main has diverged → **surface, never auto-merge**: *"local main and origin/main have diverged ({A} local / {B} remote commits) — this shouldn't happen if checkpoints used the strand guard; reconcile with `git fetch` then `git merge origin/main` (inspect first). Do NOT `git pull --ff-only` (it fails on divergence)."* The operator integrates.
+
+Cross-machine note: the flag file is machine-local, so a worktree (or the primary checkout) on another laptop relies on the opt-in `forge.worktree_rebase_check` / a periodic fetch instead — eventual, not instant.
 
 **Worktree path convention check (advisory — main or worktree).** A recorded worktree path is trusted *verbatim* everywhere (FORGE.md → "Recorded path is authoritative"), so a path created **outside** the convention — a manual `git worktree add ../forge-worktrees/m115`, or pre-convention state — is honored unchallenged by the 1.1a gate and by `chief-of-staff` adoption. This check surfaces that drift. It never blocks and never moves anything.
 
@@ -54,7 +61,11 @@ Cross-machine note: the flag file is machine-local, so a worktree on another lap
 - Mismatch → one advisory line: *"recorded worktree path `{path}` for m{id} is not under the convention root `{root}` — likely a manual `git worktree add` or pre-convention state. Fix: `git worktree move {path} {root}/{anchor}` then update the recorded path. (Advisory; honors `orchestration.worktree_root`.)"*
 - Parent dir under the root, or no recorded path → silent. An explicit `orchestration.worktree_root` is honored by construction (the override **is** the root compared against), so a deliberately relocated root never false-warns.
 
-**Stream Rollup (active.yml is derived).** If `.forge/streams/` has any stream files, regenerate `.forge/streams/active.yml` from them + active milestones per FORGE.md → Stream Rollup, the same way step 1.0 regenerates `index.yml`. `active.yml` is derived — never read it as authoritative without rolling up first, and never hand-edit it. Runs in the main checkout (worktrees never write `active.yml`). No `streams/` dir → skip.
+**ID reservation preflight (advisory — main or worktree).** The cross-worktree ID Reservation Protocol (FORGE.md, ADR-016) only protects numbers if `.forge/reservations.yml` actually carries them. Two cheap checks, both advisory — never block:
+- **Absent registry, but IDs already exist.** `.forge/reservations.yml` missing *and* the tree already holds allocated IDs (`requirements/*.yml` has `FR-`/`NFR-`/`DEF-`, or `.forge/decisions/` has `ADR-NNN`) → one-time nudge: *"No `reservations.yml` yet, but this project already allocates IDs. Concurrent worktrees will collide on the next number. Create it by reserving your next ID via the protocol (`planning`/`architecting` do this), or backfill existing IDs now."* (No IDs anywhere → silent; the first reservation creates the file lazily.)
+- **Backfill scan (un-reserved landed IDs).** When `reservations.yml` exists, diff the IDs actually landed in the tree (`FR-`/`NFR-`/`DEF-` across `requirements/*.yml`; `ADR-NNN` across `.forge/decisions/`) against the ids recorded in `reservations.yml`. Any landed ID with **no** reservation entry → list them once: *"{N} ID(s) are in the tree but not in `reservations.yml` ({ids}) — landed before the protocol or via an un-reserved path. They are still respected (next = max(reserved, in-tree)+1), but appending backfill entries keeps the registry the single audit trail."* Advisory: surface, don't auto-write — backfilling is the operator's call.
+
+**Stream Rollup (active.yml is derived).** If `.forge/streams/` has any stream files, regenerate `.forge/streams/active.yml` from them + active milestones per FORGE.md → Stream Rollup, the same way step 1.0 regenerates `index.yml`. **Run the 1.0 State Rollup (below) first** so `index.yml` is fresh — the Stream Rollup reads active milestones from it for implicit-row coverage, so on a boot where a just-merged milestone promotion lands, a stale `index.yml` would silently drop that milestone's coverage row. `active.yml` is derived — never read it as authoritative without rolling up first, and never hand-edit it. Runs in the main checkout (worktrees never write `active.yml`). No `streams/` dir → skip.
 
 **Ready-to-merge nudge (main checkout / streams without checkpoints).** From the just-regenerated `active.yml`, scan for streams with `coordination: ready` or a non-empty `merge_queue` **that are not auto-publishing via checkpoints**. Any present → one line: *"{N} stream(s) ready to merge — run `/chief-of-staff` (merge safe) to integrate."* Pointer only — the cadence logic lives in the Chief's Merge Cadence Check; `forge` never merges. Nothing pending → silent.
 
@@ -125,7 +136,7 @@ Single-owner-mutable state must be written by exactly one checkout. When this se
 Resolve the worktree path from the recorded `lifecycle.worktree_path` / `runtime.worktree`, or — if absent — from the base **Worktree Convention** (FORGE.md).
 
 **Completed milestone + live worktree → finalize, not gate (precedence).** The gate assumes the live worktree holds *in-progress, owned* work. A worktree whose milestone file is already `current.status: complete` — it set complete and merged to main, then a fresh main boot lands here — needs the **opposite** of a write-block: it needs wrapping up. So when the selected milestone is `complete` **and** still has a live worktree, do **not** raise the four-option ownership gate. Surface the finalize offer instead: *"m{id} is complete but its worktree `{path}` (`{branch}`) is still live — roll up `index.yml` and tear down the worktree + branch? [yes / keep]"*.
-- **yes** → confirm, then `git worktree remove {path}`, delete the branch, clear `lifecycle.worktree_*` on the milestone, and run **Rollup (1.0)**. (Never auto-remove without the explicit yes.)
+- **yes** → confirm, then `git worktree remove {path}`, delete the branch, clear `lifecycle.worktree_*` on the milestone, and run **Rollup (1.0)**. If a stream file backs this milestone, also close it — clear `runtime.worktree`, set `stream.status: closed` (or prompt) — and run the **Stream Rollup** so `active.yml` drops the row pointing at the torn-down worktree. (Never auto-remove without the explicit yes.)
 - **keep** → leave it; impose no write-block — a `complete` milestone has no live cursor left to fork.
 
 The gate (below) and this finalize path are mutually exclusive on `current.status`: `complete` → finalize; any other status with a live worktree → gate.
@@ -185,30 +196,7 @@ Downstream skills (researching, discussing, planning, executing, verifying, revi
 
 **Skip declined groups first.** Glob `.forge/state/desire-paths/declined/*.yml`; skip any group whose key (`type` + normalized `note`) already has a decline file — it stays dismissed, no re-nag.
 
-**Surface at 3+.** For each remaining group with 3+ files, name a CONCRETE fix from this table (co-located here so the reader that acts carries the map):
-
-| Type | Suggested evolution |
-|------|---------------------|
-| `deviation_pattern` | Add a pre-check to planning, or a new constitutional article |
-| `tier_override` | Adjust tier-detection heuristics in the forge skill |
-| `skipped_step` | Make the step optional, or merge it into another |
-| `recurring_friction` | Add guidance to the relevant skill, or create a template |
-| `agent_struggle` | Add examples or anti-patterns to the relevant skill |
-| `user_correction` | Add a rule to constitution / context.md / the relevant skill |
-
-Prompt: *"Recurring: [{note}] ({N}x, scope:{scope}). Fix: [concrete suggestion from table]. Apply / decline?"*
-
-- **Agree** → apply the fix; archive the group's files to `.forge/state/desire-paths/resolved/`.
-- **Decline** → write ONE file `.forge/state/desire-paths/declined/{date}-{type}-{slug}.yml` with `{group_key, declined_at, reason}`, so it never re-prompts. (Replaces the old "note, don't nag" — which wrote nothing, so the 3+ files re-nagged every boot.)
-- (Occurrence count is derived from file count — there is no counter to reset.)
-
-**Upstream transport — for `scope: framework` groups only** (ADR-012). A framework-scope signal's fix targets Forge's own skills/templates, which live in the Forge repo, not this project. So in addition to the Apply/decline prompt above:
-
-1. **Always** write a portable, self-contained block to `.forge/state/desire-paths/upstream/{date}-{type}-{slug}.md` — pattern, occurrence count, the sibling observation filenames, the suggested evolution (from the table), and `suggestion_target`. Formatted to paste cleanly into a GH issue. This is the durable floor; it survives even with no network/tooling.
-2. **Resolve `forge.upstream_repo`** from `project.yml`; if absent, default to `https://github.com/zayneupton/forge`. If resolvable **and** `gh` is on PATH → offer (don't auto-run — it publishes externally): `gh issue create --repo {upstream_repo} --title "[desire-path] {note}" --body-file {block}`. **The GH issue is the real close** — tracked, central, survives machine loss.
-3. If `gh`/url unavailable → note the block is on disk and harvestable by `upgrading` (which runs from a local Forge clone) into `{source}/docs/desire-paths-inbox/`.
-
-`project`-scope groups keep the in-project flow above — no upstream. Applying a framework fix locally (when this *is* the Forge repo) and routing it upstream are not mutually exclusive: in a user project you route; in the Forge repo you apply.
+**Surface at 3+.** For each remaining group with 3+ files (declined groups already skipped), **load `desire-paths-review.md` in this skill dir and follow it** — it carries the concrete fix-suggestion map (per `type`), the Apply/decline mechanics (archive to `resolved/` on apply; write a `declined/` file on decline — no re-nag), and the upstream transport for `scope: framework` signals (portable block + optional `gh issue` against `forge.upstream_repo`). Groups under 3 (the common boot) → nothing to surface; skip the load. (Occurrence count is derived from file count — no counter to reset.)
 
 ### 1.3 Interface Check
 

package/template/.claude/skills/forge/desire-paths-review.md

@@ -0,0 +1,37 @@
+# Desire-Path Review — Surfacing & Fix Map
+
+Loaded by `forge` boot (SKILL.md Step 1.2) **only when a desire-path group reaches
+3+ occurrences**. The cheap part of the review — glob, skip declined groups, count
+per group — stays inline in SKILL.md; this file carries the fix-suggestion map,
+the apply/decline mechanics, and the upstream transport for framework-scope
+signals, so the common boot (no group at 3+) never loads it.
+
+## Surface at 3+ — concrete fix map
+
+For each remaining group with 3+ files, name a CONCRETE fix from this table:
+
+| Type | Suggested evolution |
+|------|---------------------|
+| `deviation_pattern` | Add a pre-check to planning, or a new constitutional article |
+| `tier_override` | Adjust tier-detection heuristics in the forge skill |
+| `skipped_step` | Make the step optional, or merge it into another |
+| `recurring_friction` | Add guidance to the relevant skill, or create a template |
+| `agent_struggle` | Add examples or anti-patterns to the relevant skill |
+| `user_correction` | Add a rule to constitution / context.md / the relevant skill |
+
+Prompt: *"Recurring: [{note}] ({N}x, scope:{scope}). Fix: [concrete suggestion from table]. Apply / decline?"*
+
+- **Agree** → apply the fix; archive the group's files to `.forge/state/desire-paths/resolved/`.
+- **Decline** → write ONE file `.forge/state/desire-paths/declined/{date}-{type}-{slug}.yml` with `{group_key, declined_at, reason}`, so it never re-prompts. (Replaces the old "note, don't nag" — which wrote nothing, so the 3+ files re-nagged every boot.)
+- (Occurrence count is derived from file count — there is no counter to reset.)
+
+## Upstream transport — `scope: framework` groups only (ADR-012)
+
+A framework-scope signal's fix targets Forge's own skills/templates, which live in
+the Forge repo, not this project. So in addition to the Apply/decline prompt above:
+
+1. **Always** write a portable, self-contained block to `.forge/state/desire-paths/upstream/{date}-{type}-{slug}.md` — pattern, occurrence count, the sibling observation filenames, the suggested evolution (from the table), and `suggestion_target`. Formatted to paste cleanly into a GH issue. This is the durable floor; it survives even with no network/tooling.
+2. **Resolve `forge.upstream_repo`** from `project.yml`; if absent, default to `https://github.com/zayneupton/forge`. If resolvable **and** `gh` is on PATH → offer (don't auto-run — it publishes externally): `gh issue create --repo {upstream_repo} --title "[desire-path] {note}" --body-file {block}`. **The GH issue is the real close** — tracked, central, survives machine loss.
+3. If `gh`/url unavailable → note the block is on disk and harvestable by `upgrading` (which runs from a local Forge clone) into `{source}/docs/desire-paths-inbox/`.
+
+`project`-scope groups keep the in-project flow above — no upstream. Applying a framework fix locally (when this *is* the Forge repo) and routing it upstream are not mutually exclusive: in a user project you route; in the Forge repo you apply.

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

@@ -270,6 +270,10 @@ No library + UI files → *"No component library. Design system or custom?"*
 
 Present grouped. User confirms/adds/removes.
 
+### Step 6.5: Rules Layer
+
+The project ships with `.claude/rules/agent-discipline.md` (always-on AI-discipline floor). Point the user at the **rules layer** (`.claude/rules/README.md`) for codifying conventions that should auto-load by file path — cheaper than the constitution, lighter than a skill (ADR-018). If a stack was detected (Laravel/PHP, Python, Vue), offer the **opt-in convention pack**: *"Detected {stack}. Install the convention skills + path-scoped rules? `bash experimental/conventions/install.sh {stack}`"* (skip if the pack isn't present in this install). Stack conventions are opt-in — never auto-installed into the stack-agnostic core.
+
 ## Greenfield
 
 ### Step 1: Basics

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

@@ -76,11 +76,11 @@ Resolve current milestone ID from `.forge/state/index.yml` (active milestone) or
 
 If missing, create from `.forge/templates/requirements.yml`:
 1. Extract from user description + research
-2. IDs: FR-001, FR-002... **Globally unique across milestones** -- check existing `.forge/requirements/*.yml` for highest FR-ID, continue sequence
+2. IDs: FR-001, FR-002... **Globally unique across milestones.** Allocate via the **ID Reservation Protocol** (FORGE.md). **This is a blocking gate, not advisory: do not write an `FR-`/`NFR-`/`DEF-` ID into any artifact until its reservation is appended and committed.** Per ID: next = `max(highest `kind: fr` in `.forge/reservations.yml`, highest FR in `.forge/requirements/*.yml`) + 1; append `{kind: fr, id, milestone, reserved_at, summary}` to `.forge/reservations.yml`, **commit + push**, *then* write the FR. Skipping the reserve step is the exact failure ADR-016 exists to prevent — bare scan-and-increment sees only committed state, so two worktrees branched from one baseline claim the same number and collide silently until merge (a multi-file renumber). No `reservations.yml` yet ⇒ scan as before; the first reservation creates it (lazy migration), but once it exists the gate is mandatory.
 3. Acceptance: Given/When/Then
 4. Uncertain: `[NEEDS CLARIFICATION]`
 5. P1 (must) / P2 (should) / P3 (nice)
-6. Deferred: DEF-001... (also globally unique)
+6. Deferred: DEF-001..., and NFR-001... — **also globally unique; reserve the same way** (`kind: def` / `kind: nfr`) before writing.
 
 **E2E gate (M9):** For each functional requirement being added or refined:
 1. Decide `e2e: true|false` -- does this story need a post-validation e2e test?
@@ -135,6 +135,8 @@ This is the common case when starting a new milestone alongside an existing one.
 
 If a sibling milestone (e.g. m50) has state + requirements but is missing from `roadmap.yml`, that's a pre-existing gap -- flag to user, don't silently backfill.
 
+**Promoted-from-backlog milestone (`milestone.origin` set).** If `state/milestone-{N}.yml` carries `milestone.origin: {R-id}` (set by `forge` Step 1.2 when promoting a Standard-tier refactor item), no extra bookkeeping is needed here — the originating backlog item is flipped to `done` automatically when the milestone completes (see `reviewing` → **Promoted Milestone Completion Hook**). Just plan it as a normal milestone.
+
 ## Step 6: Decompose Tasks
 
 ### Step 6.1: Cross-Layer Contract Detection
@@ -205,6 +207,18 @@ Plan naming reflects the slice: `plan-01-user-signs-up.md`, not `plan-01-models.
 </task>
 ```
 
+#### Overlay / Popover must_haves (when a plan adds a floating surface)
+
+When a plan introduces an **overlay, popover, sheet, anchored panel, or any floating surface** (especially one anchored to a moving element like a canvas block), specifying its *content* (rows, keys, payload) is **not enough** — the *behavior* questions below only surface when a human touches the running UI, each costing a full build → deploy → UAT round. Add a `must_haves.truths` entry for every item that applies, phrased as a user-observable behavior:
+
+1. **Placement + edge clamp** — where does it appear relative to its anchor, and does it stay fully on-screen when the anchor is near a viewport/canvas edge?
+2. **Drag-tracking** — if the anchor can move (drag, scroll, reflow), does the overlay follow it?
+3. **Live param re-sync** — while open, does it re-read the anchor's state so it reflects live changes (not a stale snapshot from open time)?
+4. **Z-order + tap-order** — draw order *and* hit-test order versus every other overlay/popover that can be open in the same surface.
+5. **Open/dismiss lifecycle** — what opens it, what dismisses it, and what happens if another overlay opens while it is already open?
+
+Treat this as a checklist, not a template: drop the items that don't apply (a static centered modal has no anchor, so 1–3 collapse to "centered + on-screen"). The point is to decide each at plan time rather than discover it at device UAT. (Desire-path: canvaz m-SEQ01 — six overlay-behavior gaps, 5+ deploy-and-retest rounds.)
+
 #### Integration Checkpoints (merge often and early)
 
 Mark the phases where a verified slice should **land on main**, so a stream integrates continuously instead of batching at milestone end (FORGE.md → Stream Integration Checkpoints). Set `integration_checkpoint: true` in the plan frontmatter for those phases.
@@ -364,7 +378,7 @@ Prompt pattern:
 
 - **yes** — defer to `testing` after planning completes; note in plan frontmatter
 - **no** — document rationale in `context.md` Discretion Areas
-- **later** — surface again at verifying gate if UI tests still missing
+- **later** — rides on the verifying **Interface Testing Gate**: when `interface` is declared in `project.yml`, that gate already BLOCKS at verifying if UI tests are still missing (no separate planning hook needed)
 
 Decision captured once, pre-code. Does not block planning.
 

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

@@ -56,6 +56,8 @@ File lists per subagent (paths, not globs).
 
 Fresh-context subagents with file list + tech stack. **Pass `model` param** from `project.yml` model routing (`models.skills.reviewing` → `models.default` → parent). Display: *"Spawning reviewers with model: {model} (from {source})"*
 
+The `reviewer` agent (3 modes below) is the **breadth pass** that gates the health report. For high-risk diffs (auth, payments, data-access, hot paths, public-facing docs) you may **additionally** spawn the confidence-gated specialists — `security-reviewer`, `performance-reviewer`, `doc-reviewer` (ADR-018) — for defensible single-axis depth. They report only Confidence ≥ 8 (security requires a concrete exploit scenario), so their output folds into the breadth findings without noise. Optional and additive — skip for low-risk changes.
+
 ### Part 1: Security Audit
 
 | # | Category | Checks |

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

@@ -52,15 +52,15 @@ Read: .github/workflows/* → CI config (ci-check mode, analyst CI sub-check)
 3. Agent appends actionable items to `.forge/refactor-backlog.yml`:
    ```yaml
    - id: T-{NNN}
-     source: testing-analyst
-     date: YYYY-MM-DD
-     category: flake | coverage-gap | anti-pattern | quarantine
+     milestone: {active milestone id}
+     category: flake | coverage-gap | anti-pattern | quarantine-candidate | ci-gap
      file: "path/to/test.spec.ts"
      lines: "NN-NN"
      description: "What's wrong"
      effort: quick | standard
      suggested_approach: "How to fix"
      status: pending
+     added: "YYYY-MM-DD"
    ```
    ID numbering: read existing backlog, find max T-NNN, increment. No gaps.
 4. Receive agent YAML output (`suite_audit:` block). Review for completeness.

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

@@ -110,6 +110,8 @@ Runs AFTER code-level verification commands pass. Skipped if no `e2e:true` stori
 5. **Hash drift check** (run BEFORE prompting, every gate invocation): for each `e2e:true` FR with `validated: true`, recompute hash from current `observable_outcome`. If it differs from stored `observable_outcome_hash` → set `validated: false`, clear hash. Note auto-reset in verification report. Then prompt that FR as unvalidated.
 6. Write per-FR validation outcomes into the verification report under section "E2E Validation".
 
+**Exclusive-resource lease (concurrent streams + a shared physical device).** If this gate's manual walk needs an exclusive resource declared in `project.yml` `orchestration.exclusive_resources` (a physical device, a singleton emulator) **and** other streams are active, acquire the lease before deploying and release it after — otherwise a sibling stream's `device install` clobbers this build mid-walk and you verify the wrong binary (forge#15). Acquire = write `runtime.lease: {resource, acquired_at, operation: e2e-validation}` to this stream's file; the resource is busy → queue (or skip the device gate with a recorded reason) until it frees. Release = clear the field once the walk completes. Single checkout / no declared exclusive resources → no lease, proceed. See chief-of-staff → **Exclusive Resource Leases**; prefer per-stream isolation (bundle-ID suffix) over leasing when the resource can be split.
+
 ### Gate behavior
 
 - **Advisory, not blocking.** Verifying still passes even if no stories validated — the hard gate is in `testing` skill author-mode (phase 16). This gate's job is to surface + record, not block.
@@ -302,18 +304,27 @@ If GAPS found, route back to planning in gap-closure mode. Context clear applies
 Realizes producer-side continuous integration (FORGE.md → Stream Integration Checkpoints). Runs at Phase Handoff step 5, **only when all hold**:
 
 - the phase's plan frontmatter has `integration_checkpoint: true`;
-- the verdict is PASSED **and** `current.human_verified` is set (where required) — never publish unverified work;
+- the verdict is PASSED — never publish unverified work. (`current.human_verified` gates milestone **close**, *not* per-checkpoint publish: a non-final checkpoint phase publishes on PASS alone; the milestone's **final** checkpoint coincides with close, where the Human Verification Gate applies — so in practice only the last checkpoint also requires `human_verified`.)
 - the session is a **worktree** (`git rev-parse --git-dir` ≠ `--git-common-dir`). In a single checkout, skip — there is no main to fast-forward into.
 
-Then publish **fast-forward only**:
+**Strand guard — never push past the operator's local main (forge#13).** `git push origin HEAD:main` is fast-forward-only *relative to `origin/main`* — but `origin/main` is **not** the operator's canonical checkout. The local `main` ref (shared across this machine's worktrees via the common git dir) can carry commits that were never pushed — another stream's merge, a framework bump, the state-sync commits from step 4. If you push the worktree tip onto an `origin/main` that is *behind* local main, origin fast-forwards but **local main is left diverged** (it has commits origin's new tip lacks, and vice versa). The closing report then mis-reads this as "local main is behind — `git pull`", and `git pull --ff-only` *fails* on divergence while a bare `git pull` makes a surprise merge commit — the exact failure the merge discipline exists to prevent. So gate the push on local main being in the publish's direct line:
 
 ```bash
-# Push this worktree's verified commits to main. FF-only is the safety:
-# git refuses a non-ff push, so a diverged main is surfaced, never forced.
-git push origin HEAD:main            # remote present
-# no remote → fast-forward the local main ref where possible, else report ready-to-ff
+git fetch origin main 2>/dev/null || true          # refresh origin/main (no-op without a remote)
+# Publish is strand-safe only when local main is an ANCESTOR of this worktree's HEAD —
+# i.e. local main has no commits this checkpoint doesn't already contain.
+if git rev-parse --verify -q main >/dev/null 2>&1 \
+   && ! git merge-base --is-ancestor main HEAD; then
+  : "STRANDED — local main carries commits this checkpoint omits. Do NOT push."
+fi
 ```
 
-- **Success** → set the integration flag for sibling worktrees: write `.git/forge/integration-pending` (in the git common dir) with the new main sha, this stream/milestone, and the shared surfaces this phase changed. Report: *"Checkpoint published — phase {N} fast-forwarded onto main; siblings will pick it up on next boot."*
-- **Rejected (non-ff — main diverged)** → **do not force.** Surface: *"main has advanced since this worktree branched — publish needs a manual merge/rebase first."* Leave the work on the branch; the Chief's Merge Cadence Check / a human resolves it.
-- Never auto-resolve a conflict, never force-push.
+- **Strand-safe** (local main is an ancestor of HEAD, or no local `main` ref exists) → publish **fast-forward only**:
+  ```bash
+  git push origin HEAD:main          # remote present; git refuses a non-ff push (diverged origin surfaced, never forced)
+  # no remote → fast-forward the local main ref where possible, else report ready-to-ff
+  ```
+  - **Success** → set the integration flag for **all** of this machine's checkouts (sibling worktrees *and* the primary main checkout): write `.git/forge/integration-pending` (in the git common dir) with the new main sha, this stream/milestone, and the shared surfaces this phase changed. Because local main was an ancestor, advancing it is a **true fast-forward** — report: *"Checkpoint published — phase {N} fast-forwarded onto main. Local main is now behind origin by this slice; it auto-fast-forwards on the next `/forge` boot, or `git merge --ff-only origin/main` from the primary checkout now."* (Here, and only here, is local main genuinely *behind* — the ff advice is correct.)
+  - **Rejected (non-ff — `origin/main` itself diverged)** → **do not force.** Surface: *"origin/main has advanced since this worktree branched — publish needs a manual merge/rebase first."* Leave the work on the branch; the Chief's Merge Cadence Check / a human resolves it.
+- **Stranded** (local main has commits this checkpoint omits) → **do not push.** Integrating through origin would diverge local main. Surface: *"main has advanced locally ({N} commit(s) not in this checkpoint) since this worktree branched. Publishing direct to origin would strand your local main (diverged, not behind). Integrate through local main instead: from the primary checkout `git merge {branch}` (or rebase this worktree onto main, then publish). Do NOT `git pull --ff-only` — it fails on divergence."* Leave the work on the branch; a human integrates.
+- Never auto-resolve a conflict, never force-push, never auto-rebase.