forge-orkes 0.68.1 → 0.70.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.68.1",
+  "version": "0.70.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/hooks/forge-slice-runner.sh

@@ -571,7 +571,15 @@ for phase in $PHASES; do
 
     # (4) REQUIRE the on-disk phase-report.yml. Absent = crash → halt now (do NOT
     #     spend the retry on a crash; the resume path re-runs it from files).
+    #     This is a slice END, so it MUST ping like the other two ends (checks-failed
+    #     halt below, done) — a silent phone is never success. Live gap: canvaz
+    #     2026-07-23, m-EVT01 hit error_max_turns and the slice died dark. Key is
+    #     per-phase ("$phase-crash"), NOT the shared "slice" key: a crash marker on
+    #     the shared key would suppress a LATER legitimate checks-failed halt after
+    #     resume; a re-crash of the same phase stays deduped (append-once semantics).
     if [ ! -f "$report" ]; then
+      slice_notify halt "$phase-crash" \
+        "slice HALTED at phase $phase ($idx/$total) — launcher crash, no phase-report.yml written (attempt $attempt); see $wdir/result.json + $wdir/launch.err"
       printf '[runner] phase %s: no phase-report.yml written at %s — halting\n' "$phase" "$report" >&2
       printf 'SLICE_RESULT phases=%s touches=%s last_ping=%s\n' "$COMPLETED" "$TOUCHES" "$LAST_PING"
       exit 1

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

@@ -139,6 +139,8 @@ If a sibling milestone (e.g. m50) has state + requirements but is missing from `
 
 **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.
 
+**Roadmap integrity check (advisory, m-39).** After writing or updating `roadmap.yml` in any of the three cases above, run `.forge/checks/forge-roadmap-check.sh`. If it exits non-zero, surface every `finding=...` line to the operator as one advisory note (e.g. *"roadmap-check found {N} issue(s): {lines}"*). This NEVER blocks — Step 9 Present and the handoff proceed regardless of findings; it is a signal, not a gate (same advisory posture as `verification.commands` in FORGE.md → Verification Gates). Script absent (pre-m-39 install) → skip silently.
+
 ## Step 6: Decompose Tasks
 
 ### Step 6.1: Cross-Layer Contract Detection

package/template/.forge/checks/forge-roadmap-check.sh

@@ -0,0 +1,246 @@
+#!/usr/bin/env sh
+# forge-roadmap-check.sh — structural integrity check for .forge/roadmap.yml (m-39).
+#
+# Validates the roadmap against the drift class that caused the m-34/m-36 phase-id
+# collision: two independent renumbering passes both picked phase id 63. A flat
+# grep over "id: N" cannot tell a milestone's id from a phase's id from an
+# unrelated numeral (estimated_hours: 63), and cannot catch a field that drifted
+# to the wrong indentation depth. This check instead walks the file as a small
+# indentation-keyed state machine over roadmap.yml's three fixed second-level
+# blocks (milestones:/phases:/waves:) — HONEST LIMIT: it understands exactly this
+# one fixed shape, not arbitrary YAML.
+#
+#   forge-roadmap-check.sh [<roadmap-file>]      # default: <git-root>/.forge/roadmap.yml
+#
+#   stdout (machine-parseable, fold style):
+#     ok=clean                                   # no findings
+#     finding=<rule>:<detail>                     # one line per problem
+#     rule ∈ missing-field | duplicate-phase-id | dangling-phase-ref | orphan-phase
+#          | bad-milestone-dir | dangling-wave-ref
+#   exit: 0 = ok=clean; 1 = one or more findings; 2 = bad invocation (missing/unreadable file)
+#
+# Required fields (confirmed against the live file — zero false positives today):
+#   milestone entry: id, name, phases (non-empty)
+#   phase entry:     id, name, goal, requirements, dependencies, success_criteria,
+#                    estimated_hours, status
+#   milestone_dir is DELIBERATELY not required — 17/65 live phase entries predate
+#   the nested-layout convention. Validated only when present (bad-milestone-dir).
+#
+# Pure POSIX sh + awk. No git-repo dependency (reads the file directly, unlike the
+# diff-scoped forge-hold-check.sh/forge-check-lint.sh). Collects every finding in
+# one pass before deciding exit code — a single run surfaces everything wrong.
+set -u
+
+FILE="${1:-}"
+if [ -z "$FILE" ]; then
+  ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+  FILE="$ROOT/.forge/roadmap.yml"
+fi
+
+if [ ! -f "$FILE" ] || [ ! -r "$FILE" ]; then
+  echo "roadmap-check: $FILE: not found or unreadable" >&2
+  exit 2
+fi
+
+awk '
+function trim(s) {
+  gsub(/^[ \t]+|[ \t]+$/, "", s)
+  return s
+}
+function unquote(s) {
+  gsub(/"/, "", s)
+  return s
+}
+function bare_num(s,   n) {
+  n = unquote(trim(s))
+  if (n ~ /^m-/) n = substr(n, 3)
+  return n
+}
+function finish_entry() {
+  if (!entry_open) return
+  if (entry_type == "milestone") {
+    ms_count++
+    ms_id[ms_count] = cur_id
+    ms_fields[ms_count] = cur_fields
+    ms_phaselist[ms_count] = cur_phaselist
+  } else if (entry_type == "phase") {
+    ph_count++
+    ph_id[ph_count] = cur_id + 0
+    ph_fields[ph_count] = cur_fields
+    ph_mdir[ph_count] = cur_mdir
+  }
+  entry_open = 0
+  cur_id = ""; cur_fields = ""; cur_mdir = ""; cur_phaselist = ""
+}
+
+# 2-space block header
+$0 ~ /^  (milestones|phases|waves):[ \t]*$/ {
+  finish_entry()
+  block = trim($0)
+  gsub(/:$/, "", block)
+  next
+}
+
+# waves block: "    N: [a, b, c]"
+block == "waves" && $0 ~ /^    [0-9]+:/ {
+  line = $0
+  sub(/^    /, "", line)
+  split(line, kv, ":")
+  wnum = trim(kv[1])
+  rest = line
+  sub(/^[^:]*:/, "", rest)
+  if (match(rest, /\[[^]]*\]/)) {
+    ids = substr(rest, RSTART + 1, RLENGTH - 2)
+  } else {
+    ids = ""
+  }
+  wave_count++
+  wave_num[wave_count] = wnum
+  wave_ids[wave_count] = ids
+  next
+}
+
+# entry open: "    - id: 36" / "    - id: \"m-33\""
+(block == "milestones" || block == "phases") && $0 ~ /^    - id:/ {
+  finish_entry()
+  entry_open = 1
+  entry_type = (block == "milestones" ? "milestone" : "phase")
+  val = $0
+  sub(/^    - id:[ \t]*/, "", val)
+  cur_id = unquote(trim(val))
+  cur_fields = " id "
+  next
+}
+
+# 6-space field line inside an open entry
+(block == "milestones" || block == "phases") && entry_open && $0 ~ /^      [A-Za-z_]+:/ {
+  line = $0
+  sub(/^      /, "", line)
+  match(line, /^[A-Za-z_]+/)
+  field = substr(line, RSTART, RLENGTH)
+  cur_fields = cur_fields field " "
+  if (field == "milestone_dir") {
+    val = line
+    sub(/^milestone_dir:[ \t]*/, "", val)
+    cur_mdir = unquote(trim(val))
+  }
+  if (field == "phases" && entry_type == "milestone") {
+    rest = line
+    if (match(rest, /\[[^]]*\]/)) {
+      cur_phaselist = substr(rest, RSTART + 1, RLENGTH - 2)
+    }
+  }
+  next
+}
+
+# any other 4-space line inside milestones:/phases: (not "- id:") -> malformed
+# dedent: closes the current entry without opening a new one.
+(block == "milestones" || block == "phases") && $0 ~ /^    [A-Za-z_-]/ {
+  finish_entry()
+  next
+}
+
+END {
+  finish_entry()
+
+  required_ms = "name phases"
+  required_ph = "name goal requirements dependencies success_criteria estimated_hours status"
+
+  # 1. required fields
+  for (i = 1; i <= ms_count; i++) {
+    n = split(required_ms, reqs, " ")
+    for (j = 1; j <= n; j++) {
+      if (index(ms_fields[i], " " reqs[j] " ") == 0) {
+        print "finding=missing-field:milestone:" ms_id[i] ":" reqs[j]
+        found++
+      }
+    }
+  }
+  for (i = 1; i <= ph_count; i++) {
+    n = split(required_ph, reqs, " ")
+    for (j = 1; j <= n; j++) {
+      if (index(ph_fields[i], " " reqs[j] " ") == 0) {
+        print "finding=missing-field:phase:" ph_id[i] ":" reqs[j]
+        found++
+      }
+    }
+  }
+
+  # phase-id set + first-seen order tracking for duplicate detection
+  for (i = 1; i <= ph_count; i++) {
+    id = ph_id[i]
+    phase_seen[id] = phase_seen[id] "" (phase_seen[id] == "" ? "" : ",")
+    dup_list[id] = (dup_list[id] == "" ? "" : dup_list[id] ",") (ph_mdir[i] == "" ? "(none)" : ph_mdir[i])
+    dup_count[id]++
+    phase_exists[id] = 1
+  }
+
+  # 2. duplicate phase ids
+  for (id in dup_count) {
+    if (dup_count[id] > 1) {
+      print "finding=duplicate-phase-id:" id ":" dup_list[id]
+      found++
+    }
+  }
+
+  # 3. dangling-phase-ref (milestone claims a phase id with no phase entry)
+  for (i = 1; i <= ms_count; i++) {
+    m = split(ms_phaselist[i], claimed, /[ ,]+/)
+    for (j = 1; j <= m; j++) {
+      pid = trim(claimed[j])
+      if (pid == "") continue
+      claimed_by[pid] = 1
+      if (!(pid in phase_exists)) {
+        print "finding=dangling-phase-ref:milestone:" ms_id[i] ":phase:" pid
+        found++
+      }
+    }
+  }
+
+  # orphan-phase (phase entry claimed by zero milestones)
+  for (i = 1; i <= ph_count; i++) {
+    id = ph_id[i]
+    if (!(id in claimed_by)) {
+      print "finding=orphan-phase:" id ":" (ph_mdir[i] == "" ? "(none)" : ph_mdir[i])
+      found++
+    }
+  }
+
+  # 4. bad-milestone-dir (milestone_dir prefix must resolve to a real milestone id)
+  for (i = 1; i <= ms_count; i++) {
+    ms_numeral[bare_num(ms_id[i])] = 1
+  }
+  for (i = 1; i <= ph_count; i++) {
+    if (ph_mdir[i] == "") continue
+    if (match(ph_mdir[i], /^milestone-[^\/]+/)) {
+      prefix = substr(ph_mdir[i], RSTART, RLENGTH)
+      numeral = prefix
+      sub(/^milestone-/, "", numeral)
+      if (!(numeral in ms_numeral)) {
+        print "finding=bad-milestone-dir:" ph_id[i] ":" ph_mdir[i]
+        found++
+      }
+    }
+  }
+
+  # 5. dangling-wave-ref
+  for (i = 1; i <= wave_count; i++) {
+    m = split(wave_ids[i], wids, /[ ,]+/)
+    for (j = 1; j <= m; j++) {
+      pid = trim(wids[j])
+      if (pid == "") continue
+      if (!(pid in phase_exists)) {
+        print "finding=dangling-wave-ref:" wave_num[i] ":" pid
+        found++
+      }
+    }
+  }
+
+  if (found + 0 == 0) {
+    print "ok=clean"
+    exit 0
+  }
+  exit 1
+}
+' "$FILE"
+exit $?