forge-orkes 0.23.0 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.23.0",
+  "version": "0.25.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/skills/architecting/SKILL.md

@@ -68,8 +68,23 @@ Why this won.
 - {Positive consequence}
 - {Negative consequence}
 - {Future decisions this enables or blocks}
+
+## Platform & Goal Validation
+*Required for foundational/irreversible mechanisms (runtime loading, storage engine, auth model, cross-platform primitives). Omit for low-stakes single-feature decisions.*
+- **Platform reality:** Can the target platform(s) actually do this? Name the hard constraint that could forbid it (e.g. iOS code-signing forbids `dlopen` of non-bundled native code). An unvalidated "yes" here is the assumption most likely to become a dead-end years later.
+- **Goal fit:** Does this mechanism actually enable the goal it exists for, *on that platform*? (A loading mechanism for "third-party extensibility" that the platform forbids does not serve that goal there.)
+- **Carrying cost:** Count the platform-specific workarounds this mechanism requires. A high or growing count is a signal the mechanism fights the platform — record the number so it stays visible.
 ```
 
+### Framing the Option Space (before you fill in Alternatives)
+
+Enumerate options that intervene at **different layers**, not variants of one idea. For a load-cost problem, *when* you load, *whether* you load at all, *who holds the lock*, and *what it costs* are different layers; three load-*timing* options are one layer in three costumes. Always include:
+
+- the **constraint-breaker** — "eliminate the need / change the constraint / question the assumption" (e.g. static-link the dependency instead of runtime-loading it → the whole bug class cannot exist);
+- the **null option** — "do nothing".
+
+Name which assumption each option challenges. *Then* converge in Rationale. A confident-looking list of same-layer variants is the failure this guards against — breadth of the enumerator is the real safeguard, so pair this with a second perspective (or `discussing`) when the option space is wide.
+
 ## Constitutional Gate Check
 
 Before finalizing any decision, check against `.forge/constitution.md`:

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

@@ -29,7 +29,18 @@ Invoked by `orchestrating` skill when `forge_queue_commit` returns `status: conf
 4. **Test**: Run it. Capture evidence.
 5. **Eliminate**: Support or refute? Record result.
 6. **Iterate**: Next hypothesis or refine current one
-7. **Conclude**: Root cause found. Fix it.
+7. **Conclude**: Confirmation Gate passes (below) → root cause found. Fix it.
+
+## Confirmation Gate
+
+A root cause is a **commit point** — the moment a hypothesis becomes a finding that drives a fix. Run this before you write "root cause", "confirmed", "the cause", or "dominant cause" in the debug file, a commit message, or a report. Until all four hold, the claim stays labelled `hypothesis`:
+
+1. **Mechanism observed, not inferred.** The causal mechanism is directly measured — not assumed from correlation or co-occurrence. ("Event X co-occurs with the bug" is correlation, not mechanism.)
+2. **Alternatives explicitly refuted.** Each competing hypothesis is named and killed with evidence — not dismissed as "less likely". State the evidence that kills each one.
+3. **Blind-spot check (highest-value rule).** For *every absence of signal* you rely on — "0 errors", "detector silent", "watchdog never fired" — first prove the instrument **can** detect the failure mode in question. A deadline-miss detector that measures intra-callback work is structurally blind to the callback never being called; a heartbeat-keyed watchdog is blind to a hang that keeps the heartbeat fresh. **A null result from a blind instrument is not evidence.**
+4. **Falsification attempted.** A test that *could* have refuted the hypothesis was run and failed to refute it. State what that test was. If you cannot name one, you have a hypothesis, not a cause.
+
+When the gate cannot pass yet, write the claim as `hypothesis` everywhere — never `cause` / `confirmed` / `dominant`. Promote it only when 1–4 are satisfied.
 
 ## Persistent Debug File
 
@@ -123,6 +134,7 @@ Add logging before changing behavior. See what's happening before guessing.
 - **Anchoring**: Fixating on the first theory
 - **Availability bias**: Blaming the last thing changed, even if unrelated
 - **Sunk cost**: Continuing a dead-end investigation because of time spent
+- **Instrument blindness**: Trusting a null result ("0 errors", "detector silent") from a tool that structurally cannot observe the failure mode in question. See the Confirmation Gate blind-spot check.
 
 After 3 failed hypotheses, step back and re-read symptoms from scratch.
 
@@ -137,7 +149,8 @@ After 5 hypotheses tested without root cause:
 
 When root cause found:
 1. Fix the issue
-2. Add a regression test for this specific bug
-3. Commit: `fix({scope}): {description of root cause and fix}`
-4. Move debug file to `.forge/debug/resolved/`
-5. Update `.forge/state/milestone-{id}.yml` — remove from blockers
+2. **Confirm the fix addresses the mechanism, not just the symptom.** Re-run the falsification test / repro and verify the *mechanism* identified in the Confirmation Gate is gone — not merely that the symptom stopped appearing. "I stopped seeing it" is itself a premature commit: a symptom can vanish for an unrelated reason.
+3. Add a regression test for this specific bug
+4. Commit: `fix({scope}): {description of root cause and fix}`
+5. Move debug file to `.forge/debug/resolved/`
+6. Update `.forge/state/milestone-{id}.yml` — remove from blockers

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

@@ -267,6 +267,7 @@ Re-plan? Route to `planning` with summary.
 3. **Reference user's words.** "Friday" factors into every rec.
 4. **Stop when clear.** Don't manufacture uncertainty.
 5. **Now vs later.** Flag deferrable vs blocking.
+6. **Widen before narrowing.** Before converging on an approach, put options that intervene at *different layers* on the table — including the constraint-breaker ("change or eliminate the constraint") and "do nothing" — not three variants of one idea. Name the assumption each challenges, then pick. (Foundational/structural decisions formalize this in `architecting`'s option-space framing + Platform & Goal Validation.)
 
 ## Anti-Patterns
 

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

@@ -37,13 +37,19 @@ Check state files:
 2. **Check arg first.** `/forge 2` or `/forge "Auth system"`:
    - Match IDs (exact) or names (case-insensitive substring)
    - Found → auto-select: *"Resuming {id}: [{name}] -- {current.status}, {percent}%"*
-   - No match → *"No match for '{arg}'. Active:"*
-3. **Multiple (no arg):** Show active + not_started milestones with status + `last_updated`. Default most recent. After main list, show **Deferred:** section (id, name, frozen status `was: {current.status}`, defer date, reason). *"{N} active. Most recent: [{name}] ({current.status}, {date}). This one, or switch?"*
-4. **One:** Auto-select. *"Resuming: [{name}] -- {current.status}, {percent}%"*
-5. **None active:** If deferred exist, mention them: *"No active milestones. {N} deferred — 'resume milestone {id}' to reactivate."* Else → init or create.
-6. Load `milestone-{id}.yml`
-7. **Route on `current.status`, NOT `{percent}`.** Complete only at `complete`. 100% phases ≠ done -- verifying + reviewing must run.
-8. Report + **immediately route** (Step 3). Show: `current.status`, phase labels (Executed/Verified/Pending/In progress -- **never "Complete" for unverified**), `{percent}`. **No menus.** Position → action → invoke.
+   - No match → *"No match for '{arg}'. Active:"* (an explicit-but-unmatched arg does **not** fall through to the branch anchor — honor the no-match prompt)
+3. **Branch anchor (worktree → milestone).** Only when **no arg** was given. The worktree's git branch is a deterministic milestone signal — consult it *before* the timestamp default so a worktree resolves to *its own* milestone, not merely the most-recently-touched one. Run `git branch --show-current`, then match in priority order:
+   - **Exact** — branch equals any milestone's `lifecycle.worktree_branch` (a Forge-managed worktree from `orchestrating`).
+   - **Id token** — branch name contains a milestone id as a **prefixed**, delimited token: `m-{id}` or `milestone-{id}`, bounded by `/`, `-`, `_`, or start/end of string (e.g. `feat/m-RT01-pipeline-observability` → `m-RT01`). **Never match a bare number** — `feat/fix-issue-2` must not anchor to milestone `2`. Forge controls both milestone ids and worktree branch names, so the prefix is always available. Ambiguous (≥2 distinct milestone ids in the branch name) → no anchor; fall through to step 4.
+   - Matched milestone is `active`/`not_started` → **hard-select it** (skip the timestamp default): *"Anchored to {id}: [{name}] from worktree branch `{branch}` -- {current.status}, {percent}%."* → go to step 7.
+   - Matched milestone is `deferred`/`complete` → **do not auto-resume.** Surface and ask: *"Worktree branch `{branch}` points at {id}: [{name}], but it's {status}. Resume it, or pick another?"* → fall through to step 4 (never silently reactivate frozen/finished work).
+   - No branch, detached HEAD, or no match → fall through to step 4.
+4. **Multiple (no arg, no anchor):** Show active + not_started milestones with status + `last_updated`. Default most recent. After main list, show **Deferred:** section (id, name, frozen status `was: {current.status}`, defer date, reason). *"{N} active. Most recent: [{name}] ({current.status}, {date}). This one, or switch?"*
+5. **One:** Auto-select. *"Resuming: [{name}] -- {current.status}, {percent}%"*
+6. **None active:** If deferred exist, mention them: *"No active milestones. {N} deferred — 'resume milestone {id}' to reactivate."* Else → init or create.
+7. Load `milestone-{id}.yml`
+8. **Route on `current.status`, NOT `{percent}`.** Complete only at `complete`. 100% phases ≠ done -- verifying + reviewing must run.
+9. Report + **immediately route** (Step 3). Show: `current.status`, phase labels (Executed/Verified/Pending/In progress -- **never "Complete" for unverified**), `{percent}`. **No menus.** Position → action → invoke.
 
 **`{percent}` is derived on read — never stored.** Compute it, don't look it up:
 - `total` = number of phases listed for this milestone in `.forge/roadmap.yml` (the milestone's `phases:` list length).

package/template/.forge/FORGE.md

@@ -17,6 +17,7 @@ All phases: **invoke via `Skill` tool**, never native behavior. `planning` → `
 5. **Verify goals, not tasks.** "Does it work?" > "Did we finish checklist?"
 6. **Never forget.** `.forge/state/` persists across sessions. Milestones concurrent. Beads-compatible.
 7. **Pave desire paths.** Repeated deviations/corrections = signal → evolve framework.
+8. **Disconfirm before commit.** Before locking a diagnosis, a solution, or a foundational choice, run the cheap pass that could break it. A conclusion reached without an attempt to refute it is a hypothesis, not a finding. Enforced at the three commit points: `debugging` (Confirmation Gate), `discussing`/`architecting` (option-space framing), `architecting` (Platform & Goal Validation).
 
 ## Workflow Tiers