@izkac/forgekit 0.1.0

package/vendor/skills/forge/phases/implement.md

@@ -0,0 +1,76 @@
+# Implement phase
+
+Read and follow [../skills/subagent-driven-development/SKILL.md](../skills/subagent-driven-development/SKILL.md).
+
+Every implementer subagent must follow [../references/tdd-core.md](../references/tdd-core.md) (condensed TDD rules — the brief includes the pointer; full skill only when stuck).
+
+On test failures or unexpected behavior, use [../skills/systematic-debugging/SKILL.md](../skills/systematic-debugging/SKILL.md) before proposing fixes.
+
+**Test strategy:** [../references/test-strategy.md](../references/test-strategy.md) — tier 1 (scoped TDD) + tier 2 (narrow task evidence) during implement; **tier 3 (full workspace) runs once at verify**, not per task.
+
+**Pace:** Read `resolvedPace` / effective knobs from `forge status` (or [../references/pace.md](../references/pace.md)). After each task, decide whether to dispatch a reviewer via `review.perTask` + hard floor:
+
+| `review.perTask` | When to dispatch reviewer |
+| ---------------- | ------------------------- |
+| `always` | After every task (`thorough`) |
+| `per-group` | When the task closes a `tasks.md` group (`##` section — OpenSpec or specs engine), or immediately if the task is high-risk (`standard`) |
+| `high-risk-only` / `never` | Only when hard-floor high-risk |
+
+When skipping the reviewer, still write `task-review.md` with `APPROVED (pace self-check)` and keep tier-2 evidence mandatory for behavior changes. For `per-group` reviews, cover all tasks in that section in one reviewer pass; save as `group-review.md` next to the group’s tasks (or under `.forge/sessions/<id>/tasks/group-<nn>-<slug>/group-review.md`). Prefer `--tier fast` when `models.bias` is `prefer-fast` and the task is mechanical. Cap fix→re-review loops at `review.maxRounds`.
+
+## Plan source
+
+| planType | Task list |
+| -------- | --------- |
+| `openspec` | `openspec/changes/<name>/tasks.md` via **`/forge:apply`** (preferred), **`openspec-apply-change`** / `/opsx:apply` |
+| `specs` | `<specsDir>/changes/<name>/tasks.md` (default `specs/`) — read directly; no vendor CLI steps |
+
+Legacy sessions with planType `throwaway` or `direct`: resume from the session's own artefacts (`plan.md` / `brainstorm/notes.md`); new work always uses the configured engine (`openspec` or `specs`).
+
+For OpenSpec: follow `openspec-apply-change` for CLI steps, but **wrap each task** in the subagent loop (do not implement all tasks inline in coordinator context). For specs: read `proposal.md` / `design.md` / `tasks.md` from the change dir as context, then run the same subagent loop.
+
+## Runtime integrity (hard)
+
+Honor [../references/runtime-integrity.md](../references/runtime-integrity.md) in every brief and review packet:
+
+- Briefs **must never** contain “stub OK”, “later task”, “minimal poll loop only”, or equivalent. Shrink scope only by stopping and asking the user.
+- Capability specs beat narrow task wording. Fill reviewer `{CAPABILITY_SPEC_EXCERPT}` from the change's capability specs — not only the task line.
+- Do not mark a section complete if libraries exist but nothing in the production path calls them.
+- **Deferrals:** if wiring genuinely lands in a later task, register it — `forge defer add --task <id> --reason "…"` — and resolve it when that task lands. Unregistered "later" is a REJECT; unresolved deferrals block `forge phase done`.
+- **Spine:** when a task wires a capability into production, update its `spine.json` row (runtimeOwner / writes / evidence). `forge spine check` must pass before verify ends.
+
+## Per-task loop
+
+1. Extract full task text + file paths + relevant **capability** spec sections (not only the task checkbox line).
+2. Write `.forge/sessions/<id>/tasks/<nn>-<slug>/brief.md` using [../subagents/implementer-prompt.md](../subagents/implementer-prompt.md).
+3. Dispatch **implementer** subagent — brief includes [../references/tdd-core.md](../references/tdd-core.md). **Model:** resolve via `forge resolve-model --tier <fast|standard|capable>` (billing defaults to **`included`** — subscription/first-party pool; never invent API model slugs). Use `fast` for mechanical tasks (1–2 files, complete spec) and batched small tasks; `standard` for multi-file integration; escalate one capability tier (still `included`) when re-dispatching after `BLOCKED`. If `omitModel` is true, omit the Task `model` parameter.
+4. **Reviewer** (unless pace skips it):
+   - **`always` / high-risk hard floor:** dispatch [../subagents/task-reviewer-prompt.md](../subagents/task-reviewer-prompt.md) for this task → `task-review.md`.
+   - **`per-group` at group boundary:** dispatch one reviewer covering **all tasks in the just-finished `tasks.md` group** → `group-review.md` (include each task id + paths). Mid-group low-risk tasks: self-check `task-review.md` only.
+   - If `review.depth` is `spec-only`, focus on spec + tests evidence. Fill `{DIFF_RANGE}` and `{CAPABILITY_SPEC_EXCERPT}` — read actual code, not the implementer's summary. **Model:** `forge resolve-model --tier standard` (or `capable` for money/auth/contracts; use `fast` when `models.bias` is `prefer-fast` and not high-risk). Do **not** skip high-risk tasks.
+5. Fix loop until the reviewer approves (max `review.maxRounds` from pace; then escalate to the human). For group reviews, fix any rejected task in the group before continuing to the next group.
+6. Record **test evidence** from the implementer's report (every task, even when review is deferred to group end):
+   ```bash
+   forge evidence --task <nn>-<slug> --command "<tier-2 cmd>" --exit 0 --summary "<pass summary>"
+   ```
+   (Refuses non-zero exit without `--allow-fail`; template + rules in [../references/test-evidence.md](../references/test-evidence.md).)
+7. Mark task complete (`tasks.md` `- [x]` or update `tasksComplete`). Detect group boundary: next line in `tasks.md` is a new `##` heading, or no remaining tasks under the current heading.
+8. Repeat.
+
+**Batching:** consecutive small same-area tasks (docs, config, wording) may share one implementer brief + one review — see the batching rules in [subagent-driven-development](../skills/subagent-driven-development/SKILL.md). Never batch money/auth/contract/migration tasks.
+
+```bash
+forge phase implement --tasks-complete <N> --subagents <total dispatched so far>
+```
+
+## Forge constraints (include in every brief)
+
+- **No** autonomous `git commit` or `git push`
+- **Tier 2 tests only** before claiming task done — narrowest command for this task ([test-strategy.md](../references/test-strategy.md)); **not** the full workspace suite unless the task requires it
+- Trace ecosystem consumers when contracts change
+- Minimal diff — surgical changes only
+- Runtime integrity: no stubs / false success; name the runtime caller; tests must fail on a no-op ([runtime-integrity.md](../references/runtime-integrity.md))
+
+## After all tasks
+
+Proceed to [verify.md](./verify.md) then [review.md](./review.md).

package/vendor/skills/forge/phases/plan-openspec.md

@@ -0,0 +1,40 @@
+# Plan phase — OpenSpec
+
+Thin wrapper around the project **`openspec-propose`** skill (or `/opsx:propose`).
+
+## Steps
+
+1. Derive change name with correct product prefix (`openspec/config.yaml` (if the project uses OpenSpec prefixes)).
+2. Run `openspec-propose` / `/opsx:propose <prefix>-<slug>`.
+3. Confirm `tasks.md` exists and change is apply-ready.
+4. **Spine (always) + orchestration seam** — see [../references/runtime-integrity.md](../references/runtime-integrity.md):
+
+   ```bash
+   forge spine init     # mandatory every change — fill rows or set notApplicable
+   ```
+
+   Sync-only / docs-only: `"notApplicable": "<reason>"`. Capability work: one row
+   per REQ cluster (library → runtime owner → writes → evidence).
+
+   If the change also involves workers, job queues, handlers, or cross-runtime
+   calls, `tasks.md` MUST include:
+
+   - Explicit **wiring** tasks per job kind / entry point → domain pipeline
+   - One **product-loop acceptance** task (last implement task, before verify)
+
+   Missing spine = plan **not** ready. (`forge phase done` refuses without a
+   valid spine — keyword sniffing does not decide.)
+
+5. Update session:
+   ```bash
+   forge phase plan --plan-type openspec --openspec <change-name>
+   forge phase implement --tasks-total <N>
+   ```
+   Count tasks from `tasks.md` checkboxes.
+
+6. Get user approval to proceed to implement (unless they already said "go").
+
+## Session tracking
+
+Forge session holds orchestration artefacts; canonical plan lives under
+`openspec/changes/<name>/`.

package/vendor/skills/forge/phases/plan-specs.md

@@ -0,0 +1,97 @@
+# Plan phase — built-in specs engine
+
+For projects with `.forge/config.json` → `plan.engine: specs`. Mirrors the
+OpenSpec propose flow without the vendor CLI. Change lives under
+`<specsDir>/changes/<change-name>/` (default `specs/changes/…`).
+
+## Steps
+
+1. Derive a kebab-case change name from the brainstorm outcome (e.g.
+   `add-stripe-refunds`). No date prefix while active.
+2. Create the change directory (preferred: CLI scaffold):
+
+   ```bash
+   forge change new <change-name>
+   ```
+
+   Or create manually under `<specsDir>/changes/<change-name>/` with:
+
+   **`proposal.md`** (required)
+
+   ```markdown
+   # <Change title>
+
+   ## Why
+   One or two paragraphs: problem / pressure.
+
+   ## What Changes
+   Bulleted scope — behavior, contracts, data.
+
+   ## Impact
+   Affected code/areas, risks, migration notes.
+   ```
+
+   **`design.md`** (only when there are real design decisions)
+
+   Context, decisions with alternatives, risks. Skip for mechanical changes.
+
+   **`tasks.md`** (required)
+
+   ```markdown
+   # Tasks
+
+   ## 1. <Group name>
+   - [ ] 1.1 <Bite-sized task — exact files, expected tests>
+   - [ ] 1.2 …
+
+   ## 2. <Group name>
+   - [ ] 2.1 …
+   ```
+
+   Task-writing rules (from writing-plans practice):
+   - Bite-sized: one task = one reviewable step (a test + the code to pass it).
+   - Name exact file paths where known.
+   - Each task states its verification (test command or observable behavior).
+   - Group with `##` sections — Forge reviews per group under `standard` pace.
+
+3. Confirm `tasks.md` exists and the change is apply-ready.
+4. **Spine (always) + orchestration seam** — see [../references/runtime-integrity.md](../references/runtime-integrity.md):
+
+   ```bash
+   forge spine init     # mandatory every change — fill rows or set notApplicable
+   ```
+
+   Sync-only / docs-only: `"notApplicable": "<reason>"`. Capability work: one row
+   per REQ cluster (library → runtime owner → writes → evidence).
+
+   If the change also involves workers, job queues, handlers, or cross-runtime
+   calls, `tasks.md` MUST include:
+
+   - Explicit **wiring** tasks per job kind / entry point → domain pipeline
+   - One **product-loop acceptance** task (last implement task, before verify)
+
+   Missing spine = plan **not** ready. (`forge phase done` refuses without a
+   valid spine — keyword sniffing does not decide.)
+
+5. Update session:
+
+   ```bash
+   forge phase plan --plan-type specs --openspec <change-name>
+   forge phase implement --tasks-total <N>
+   ```
+
+   Count tasks from `tasks.md` checkboxes. (`--openspec` carries the change
+   name for both engines.)
+
+6. Get user approval on the artefacts before implementing (unless they already said "go").
+
+## Compatibility
+
+Layout and conventions are deliberately identical to OpenSpec
+(`proposal.md` / `design.md` / `tasks.md`, archive on finish). Migration:
+`openspec init`, then move `specs/changes/*` into `openspec/changes/`.
+
+## Session tracking
+
+Forge session holds orchestration artefacts; the canonical plan lives under
+`<specsDir>/changes/<change-name>/`.

package/vendor/skills/forge/phases/review.md

@@ -0,0 +1,25 @@
+# Review phase
+
+Per-task reviews happen inside [implement.md](./implement.md). This phase covers **final** review before finish.
+
+Read and follow [../skills/requesting-code-review/SKILL.md](../skills/requesting-code-review/SKILL.md).
+
+**Pace:** Check `review.final` via [../references/pace.md](../references/pace.md) / `forge status`. If pace skips final review and the session is not high-risk, write `.forge/sessions/<id>/reviews/final-review.md` with `SKIPPED (pace=…)` and proceed. High-risk sessions (money/auth/contracts/migrations) always get a final review (hard floor).
+
+Otherwise dispatch the final reviewer using [../subagents/final-reviewer-prompt.md](../subagents/final-reviewer-prompt.md) (whole-session verdict; the reviewer applies the checklist from [code-reviewer.md](../skills/requesting-code-review/code-reviewer.md)).
+
+**Model:** `forge resolve-model --tier capable` (or `standard`/`fast` when `models.bias` is `prefer-fast` and not high-risk; billing **`included`** by default). If `omitModel` is true, omit the Task `model` parameter; otherwise pass `model` exactly. Do not use metered/API models unless the user explicitly requests them.
+
+<HARD-GATE>
+Do NOT hand-pick a model slug for the final reviewer — not even "the most capable" from the host's model list. Resolver output only. On dispatch failure, re-resolve; do not substitute a slug yourself.
+</HARD-GATE>
+
+Save output to `.forge/sessions/<id>/reviews/final-review.md`.
+
+```bash
+forge phase review
+```
+
+Address Critical and Important findings before finish.
+
+Then proceed to [finish.md](./finish.md).

package/vendor/skills/forge/phases/verify.md

@@ -0,0 +1,120 @@
+# Verify phase
+
+Read and follow [../skills/verification-before-completion/SKILL.md](../skills/verification-before-completion/SKILL.md) and [../references/test-strategy.md](../references/test-strategy.md).
+
+## Required checks
+
+### 1. Audit tier 2 evidence (per task)
+
+For each completed task under `.forge/sessions/<id>/tasks/<nn>-<slug>/`:
+
+- `test-evidence.md` exists with command, exit code `0`, and pass summary (or key output lines).
+- `task-review.md` shows **APPROVED** (legacy sessions: `spec-review.md` + `quality-review.md`).
+- Evidence uses tier 2 scope (narrow) unless the task documented a tier-2 full-workspace exception.
+
+If any task lacks evidence, shows non-zero exit, or reviewers rejected test coverage → **stop** and fix or re-dispatch that task's implementer.
+
+**Do not** re-run tier 2 commands here — audit the artifacts.
+
+### 2. Tier 3 (scope from pace)
+
+After tier 2 audit passes, honor `verify.tier3` from [../references/pace.md](../references/pace.md) / `forge status`:
+
+| `verify.tier3` | Action |
+| -------------- | ------ |
+| `full-workspace` | One fresh full test per affected workspace (default thorough/standard) |
+| `affected-only` | Full test only for workspaces touched by this change |
+| `audit-tier2-only` | Do **not** run the suite; record deferral to push/CI in `verify-evidence.md` |
+
+```bash
+npm test (affected package/workspace)
+```
+
+When contracts changed and tier3 is not `audit-tier2-only`, also run tests in downstream consumer workspaces (project ecosystem-impact policy).
+
+Save to `.forge/sessions/<id>/verify-evidence.md`:
+
+```markdown
+# Verify evidence — tier 3
+
+- **Workspaces:** your-workspace, …
+- **Command:** `npm test -- path/to/scoped.test.ts`
+- **Exit code:** 0
+- **Summary:** 142/142 pass (or paste last ~30 lines)
+- **Run at:** 2026-06-07T12:00:00Z
+```
+
+Cite this file when claiming the implementation passes. Exit code must be `0` before leaving verify.
+
+### 2b. Strict typecheck — enforced at the gate, not here
+
+Tier 3 runs **tests**, and Vitest transpiles without type-checking — so green tests do
+**not** prove the code compiles under strict `tsc`. You do **not** need to run the full
+build gate to leave verify — strict typecheck is enforced automatically by the `pre-push`
+hook (diff-scoped, on every push / launcher **Publish**) and the full typecheck + tests on
+`development` by CI. If you want local certainty on the types you touched, optionally run:
+
+```bash
+npm run build:packages           # fresh dist/ so dependents resolve current .d.ts
+node scripts/agent-check.mjs     # strict typecheck + tests for the diff-affected workspaces
+```
+
+— but a clean tier-3 test audit is the bar to leave verify; the Publish/push + CI gate
+(`shared-build-gate` capability) catches any strict-mode breakage before it's shared.
+
+### 3. Runtime wiring audit
+
+Honor [../references/runtime-integrity.md](../references/runtime-integrity.md).
+
+For each requirement in the change's **capability specs** (not only `tasks.md`):
+
+- Name the **production caller** (job kind, endpoint, CLI, …) that invokes the implementing code.
+- Library-only / stub handler / false success / enqueueable-but-unhandled kind → **stop**. Add wiring or mark explicit gaps; do not advance.
+
+Record the trace in `verify-evidence.md` (a short REQ → caller table is enough).
+
+### 4. Product-loop E2E or BLOCKED
+
+Before leaving verify / claiming the change complete:
+
+1. Run (or document exact commands for) the **closed product loop** — not a single job slice. When the design has a producer/consumer split (analyze vs execute, proposals vs ratify), the loop is: produce artifact → consumer reads it → decision/state change → **next run's output differs from baseline**. Record it under a `## Product loop` heading in `verify-evidence.md` (the done gate greps for it). **Or**
+2. Leave an explicit **`BLOCKED`** list in `verify-evidence.md` explaining why E2E cannot run here — the done gate then refuses `done` until unblocked or the user signs `--allow-incomplete`.
+
+Also enforce **job-kind closure**: every product-surface job kind is wired end-to-end or deleted from enums/API/UI before complete. And the **consumer–producer rule**: anything the UI/API reads must be proven written by the production path.
+
+Do **not** mark the change complete or advance to `done` while a critical path is stubbed, unwired, or unverified without `BLOCKED`. Green unit/tier-3 suites alone are not enough when jobs/workers/orchestration are in scope (`integrity.requireE2E`).
+
+### 5. Mechanical gate
+
+```bash
+forge spine check        # every capability row wired (library → runtime owner → writes → evidence)
+forge defer list         # no unresolved deferrals
+forge integrity-check    # combined; forge phase done runs the same checks
+```
+
+Fix any failure before proceeding — `forge phase done|finish` refuses on the same problems.
+
+### 6. Plan completeness
+
+- Confirm every plan task is marked complete.
+- Confirm no tier 2 evidence contradicts another.
+- For OpenSpec: `openspec instructions apply --change "<name>" --json` shows expected progress.
+- Requirements met = line-by-line vs **capability specs**, not vs a narrowed task reading.
+
+```bash
+forge phase verify
+```
+
+## When to re-run tier 3
+
+- Tier 3 failed (fix, then re-run tier 3)
+- Coordinator edited code after `verify-evidence.md` was recorded
+- Quality or final reviewer flagged test gaps
+- User explicitly asks for a fresh run
+
+## When NOT to re-run
+
+- Tier 2 narrow commands — already audited; duplicating them is slow and redundant
+- Tier 3 passed and nothing changed since — do not run full suite again "for freshness"
+
+Then proceed to [review.md](./review.md) if not already done per task.

package/vendor/skills/forge/references/forge-layout.md

@@ -0,0 +1,85 @@
+# `.forge/` session layout
+
+Gitignored scratch space. Only [`.forge/README.md`](../../../.forge/README.md) is committed.
+
+## Per-checkout active session
+
+`.forge/active.json`:
+
+```json
+{
+  "sessionId": "2026-06-05T143022Z-my-feature-a3f9b2",
+  "sessionPath": ".forge/sessions/2026-06-05T143022Z-my-feature-a3f9b2",
+  "updatedAt": "2026-06-05T14:30:22.000Z"
+}
+```
+
+One active session per checkout (same pattern as `.impeccable/active.json`).
+Optional `cursorChatId` on `session.json` when available — not required.
+
+## Session directory
+
+```
+.forge/
+  active.json
+  models.local.json            ← optional; only after `forge:models -- <lane>`
+  preferences.local.json       ← optional; only after `forge:prefs -- <pace>`
+  sessions/<session-id>/
+    session.json
+    status.json
+    brainstorm/
+      notes.md
+      decisions.md
+    plan.md                    ← throwaway plans only
+    verify-evidence.md         ← tier 3 (scope from pace)
+    tasks/
+      01-<slug>/
+        brief.md
+        test-evidence.md
+        task-review.md
+    reviews/
+      final-review.md
+```
+
+Bare `forge models` / `forge:prefs` **print** effective values from committed
+defaults and do **not** create the `*.local.json` files. See [pace.md](./pace.md) and
+[docs/forge.md](../../../docs/forge.md) § Checkout-local overrides.
+
+## session.json fields
+
+| Field | Description |
+| ----- | ----------- |
+| `id` | Session directory name |
+| `slug` | Short kebab label |
+| `phase` | Current Forge phase |
+| `planType` | `openspec` (default for new work), or legacy `throwaway` / `direct` |
+| `openspecChange` | Change folder name when `planType: openspec` |
+| `forgeSkipped` | `true` if user invoked `/forge:skip` |
+| `tasksTotal` / `tasksComplete` | Implementation progress |
+| `pace` | Requested pace (`auto` \| `thorough` \| `standard` \| `brisk` \| `lite`) |
+| `resolvedPace` | Concrete pace after auto resolve or pin |
+| `paceReason` | Why auto picked this pace |
+| `paceSignal` | Text used for auto resolve |
+| `pacePinned` | `true` when checkout/session set an explicit concrete pace |
+
+Under `standard` (`review.perTask: per-group`), also write `group-review.md` when an OpenSpec `tasks.md` section completes (see [pace.md](./pace.md)).
+
+| `preferencesOverride` | Optional session-only prefs patch |
+| `createdAt` / `updatedAt` | ISO timestamps |
+
+## Retention
+
+**14 days.** Run `forge cleanup` to prune old or finished sessions.
+
+## Scripts
+
+| Script | Purpose |
+| ------ | ------- |
+| `forge new <slug>` | Create session + set active (resolves pace; warn-only doctor) |
+| `forge status` | Read active session (+ effective pace) |
+| `forge prefs` | Get/set pace preferences |
+| `forge doctor` | OpenSpec project + CLI check |
+| `forge phase <phase>` | Update phase |
+| `forge cleanup` | Prune stale sessions |
+
+Pace matrix: [pace.md](./pace.md).

package/vendor/skills/forge/references/pace.md

@@ -0,0 +1,115 @@
+# Forge pace (thoroughness)
+
+Checkout-local preferences control how much review/verify ceremony Forge runs.
+Defaults live in `preferences.defaults.json`; optional overrides in
+gitignored `.forge/preferences.local.json` (**file appears only after a set**).
+
+```bash
+forge prefs                         # print effective — does NOT write a file
+forge prefs -- auto|thorough|standard|brisk|lite   # WRITE preferences.local.json
+forge prefs -- --set review.perTask=always
+forge prefs --session-set brisk  # this session only (no local file)
+forge prefs -- --resolve --signal "add stripe refund"
+forge doctor                        # OpenSpec project + CLI
+```
+
+Billing lane (orthogonal): `forge models` prints only;
+`forge models included|metered` writes `.forge/models.local.json`.
+See [docs/forge.md](../../../docs/forge.md) § Checkout-local overrides.
+
+## Announce
+
+At session start: `Using Forge for this work. Pace: auto → brisk (…)` (use
+`resolved` from `forge status` / session reminder).
+
+## Presets (effort matrix)
+
+| Knob | `thorough` | `standard` | `brisk` | `lite` |
+|------|------------|------------|---------|--------|
+| **review.perTask** | always | per-group | high-risk-only | never\* |
+| **review.final** | always | always | high-risk-only | never\* |
+| **review.depth** | full | full | spec-only | spec-only |
+| **review.maxRounds** | 3 | 2 | 1 | 0 |
+| **verify.tier3** | full-workspace | full-workspace | affected-only | audit-tier2-only |
+| **models.bias** | default | default | prefer-fast | prefer-fast |
+| **brainstorm.depth** | full | full | short (≤2–3 options) | minimal |
+
+\*Hard floor: money / auth / shared contracts / migrations / secrets **always**
+get a per-task review (and final review if the session touched high-risk work),
+even under `lite` / `brisk` / mid-group `standard`.
+
+**`thorough` vs `standard`:** thorough reviews **every task**; standard reviews once per **OpenSpec group** (top-level `##` section in `tasks.md`), except high-risk tasks which still get an immediate per-task review.
+
+**`auto`:** resolve once at session start from signals; sticky for the session (not a separate knob matrix).
+
+## Auto signals (stricter wins)
+
+1. money, payment, stripe, billing, auth, oauth, hmac, secret, migration, contract, gdpr → **thorough**
+2. ecosystem, cross-workspace, multi-file, openapi, public API, shared package, **worker**, **job queue**, **pipeline**, **etl**, **service(s)**, **platform**, **orchestration**, **openspec**, **forge:apply**, **harmonization** → **standard**
+3. docs, readme, rename, typo, scaffold, wording, comment, changelog → **lite**
+4. fix, tweak, button, toolbar, style, padding, alignment, copy, label (explicitly small) → **brisk**
+5. else (including empty / unrecognized scope) → **standard** (fail closed — never default to brisk)
+
+### Task-count escalation
+
+When `forge phase … --tasks-total N` sets **N ≥ 15** and the session's
+`resolvedPace` is still `brisk` or `lite` (and pace is **not** user-pinned),
+Forge escalates the session to **`standard`** with
+`paceReason: "escalated: N tasks"`. Slug keywords are a poor proxy for scope;
+task count is known at plan time.
+
+## Runtime integrity
+
+Always-on rules (all paces): [runtime-integrity.md](./runtime-integrity.md) —
+no stubs / false success, runtime owner required, tests must fail on a no-op,
+specs beat narrow tasks, E2E-or-BLOCKED before done. Defaults:
+`integrity.forbidStubs`, `integrity.specsBeatNarrowTasks`,
+`integrity.requireE2E` in `preferences.defaults.json` (surfaced by `forge status`).
+
+## Agent rules by knob
+
+### `review.perTask`
+
+Cadence for the task/group reviewer (name is historical — values cover more than “per task”):
+
+- `always` — dispatch task reviewer after **every** implementer (`thorough`).
+- `per-group` — dispatch one reviewer when an OpenSpec **group** completes (`standard`). A group is a top-level `##` section in `openspec/changes/<name>/tasks.md` (all `- [ ]` items under that heading until the next `##`). Mid-group low-risk tasks get a pace self-check `task-review.md` only. If `tasks.md` has **no** section headings, treat the whole file as one group (review once when all tasks are done). High-risk tasks still get an **immediate** per-task review (hard floor).
+- `high-risk-only` — skip reviewer for low-risk tasks; still write a short self-check note in `task-review.md` (`APPROVED (pace: brisk/lite — self-check)`).
+- `never` — same as high-risk-only after hard floor (low-risk may self-check only).
+
+### `review.final`
+
+- Skip final reviewer subagent when `never` / `high-risk-only` and session is not high-risk; write `reviews/final-review.md` noting `SKIPPED (pace=…)`.
+
+### `review.depth`
+
+- `spec-only` — task reviewer checks spec compliance + tests evidence; skip broad quality essay.
+- `full` — spec then quality (existing task-reviewer prompt).
+
+### `review.maxRounds`
+
+- Cap fix→re-review loops; after the cap, escalate to the human with remaining findings.
+
+### `verify.tier3`
+
+- `full-workspace` — current verify.md behavior.
+- `affected-only` — run tests only for workspaces touched by the change (still record `verify-evidence.md`).
+- `audit-tier2-only` — audit per-task evidence; do **not** run full suite; note deferred to push/CI in `verify-evidence.md`.
+
+### `models.bias`
+
+- `prefer-fast` — prefer `--tier fast` for implementers when the brief is mechanical; reviewers use `fast` unless high-risk (then `standard`).
+- `default` — existing role-based tiers.
+
+### `brainstorm.depth`
+
+- `full` — existing brainstorming skill.
+- `short` — at most 2–3 approaches; faster approval.
+- `minimal` — confirm intent + one approach; skip long exploration when design is obvious.
+
+## Unchanged (all paces)
+
+- Tier 1 TDD + tier 2 `test-evidence.md` for behavior changes.
+- No autonomous git commit/push.
+- OpenSpec propose/apply/archive when in Forge.
+- `/forge:skip` still exits Forge entirely.

package/vendor/skills/forge/references/plan-routing.md

@@ -0,0 +1,51 @@
+# Plan routing — engine from project config
+
+Forge always produces a tracked change; the **engine** comes from
+`.forge/config.json` → `plan.engine` (written by `forge init`):
+
+| `plan.engine` | Plan phase | Change location |
+| ------------- | ---------- | --------------- |
+| `openspec` (or config missing + `openspec/config.yaml` present) | [../phases/plan-openspec.md](../phases/plan-openspec.md) | `openspec/changes/<name>/` |
+| `specs` | [../phases/plan-specs.md](../phases/plan-specs.md) | `<plan.dir>/changes/<name>/` (default `specs/`) |
+
+<HARD-GATE>
+Do NOT ask the user to choose a plan mode or engine. The engine is project
+config, not conversation. After brainstorm approval, proceed directly to the
+configured engine's propose flow.
+</HARD-GATE>
+
+## Rule
+
+**If work warrants Forge, it warrants a tracked change.** Work that is too
+small for a tracked change should **not** enter Forge — execute directly or
+use `/forge:skip`.
+
+## After brainstorm approval
+
+Follow the phase file for the configured engine — prefix (OpenSpec projects),
+propose, set-phase, approval. Do **not** offer throwaway `.forge/.../plan.md`
+or direct-from-brainstorm implementation paths.
+
+## Engine not configured
+
+If `.forge/config.json` has no `plan` block and there is no
+`openspec/config.yaml`, tell the user to run `forge init` (which offers
+OpenSpec setup or the built-in specs engine) — do not invent a layout.
+
+## Triage alignment
+
+Triage rules live in [substantial-work.md](./substantial-work.md). Before
+bootstrapping a session, confirm the work would produce a tracked change under
+the configured engine; when ambiguous, ask one clarifying question.
+
+## Legacy plan types
+
+`planType: throwaway` and `planType: direct` on **existing** sessions may
+finish per [../phases/finish.md](../phases/finish.md). Do not start new
+sessions with those modes.
+
+## Scope growth mid-session
+
+If implement scope grows beyond the approved change, stop and extend the
+current change (or propose a follow-up change) — do not fall back to throwaway
+or direct planning.