forgedock 1.5.0 → 1.6.0

package/commands/work-on/build/architect.md

@@ -29,7 +29,7 @@ COMPLEXITY_BAND=$(gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
 COMPLEXITY_BAND="${COMPLEXITY_BAND:-STANDARD}"
 ```
 
-**If COMPLEXITY_BAND: TRIVIAL** → skip all phases (A0 through A5), post NO comment, return empty plan to caller immediately. Do not read any files. This is not an error — trivial single-file changes have no cross-path consistency risk. <!-- Added: forge#679 -->
+**If COMPLEXITY_BAND: TRIVIAL** → skip all phases (A0 through A5), **post the minimal skip marker comment described in "Skip Marker" under Skip Conditions below** (reason: `TRIVIAL complexity band`), then return an empty plan to caller immediately. Do not read any files. This is not an error — trivial single-file changes have no cross-path consistency risk. The skip marker (ending in `<!-- FORGE:ARCHITECT:COMPLETE -->`) is what makes a legitimate skip observable to the headless engine's marker-only gate, so the issue advances to build instead of being stranded at `needs-human`. <!-- Added: forge#679; skip-marker on skip: forge#2689 -->
 
 **If COMPLEXITY_BAND: STANDARD or COMPLEX** → proceed to Phase A0 below.
 
@@ -668,14 +668,39 @@ gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:ARCHITECT -->
 
 ## Skip Conditions
 
-Skip this entire step (post nothing, return empty plan to caller) if:
+Skip the planning work (Phases A0–A5) and return an empty plan to caller — **but always post the Skip Marker below first** — if:
 - **COMPLEXITY_BAND: TRIVIAL** — checked via FORGE:FAST_PATH comment at entry (see guard above) <!-- Primary skip path: forge#679 -->
 - Issue creates only **new files** with no callers to find (e.g. a new command file with no existing integration point yet)
 - Issue is a 1-file config or docs edit with no code logic
 - Issue title starts with "docs:" or "chore:"
 - `{AFFECTED_FILES}` is empty
 
-When skipped, the builder proceeds with investigation report + context briefing only.
+When skipped, the builder proceeds with investigation report + context briefing only (see Integration Point below — the builder falls back gracefully on an empty plan).
+
+### Skip Marker (MANDATORY on every skip — do NOT post nothing) <!-- forge#2689 -->
+
+**Do not post nothing.** The headless engine gate (`bin/engine/phases.mjs` → `architect.detectOutcome`) treats a **missing** `FORGE:ARCHITECT:COMPLETE` sentinel as a phase **failure**, retries to `maxAttempts` (3), then strands the issue at `needs-human`. It reads GitHub comment markers only — it cannot see this subcommand's in-process "empty plan" return value. So a skip that posts no marker is indistinguishable from a crashed architect run and deterministically strands **every** `chore:`/`docs:`/trivial issue.
+
+On **every** skip branch above, post exactly this minimal comment (substitute the concrete `{SKIP_REASON}`, e.g. `chore:/docs: title`, `TRIVIAL complexity band`, `new files only — no callers`, or `AFFECTED_FILES empty`) **before** returning the empty plan:
+
+```bash
+# The skip marker is mandatory and un-gated by design — posting it IS the point
+# (a missing marker strands the issue at needs-human; see above). Same report-only
+# risk class as the unguarded plan post in "Output Format" above, so it carries the
+# same allowlist rather than a DRY_RUN guard.
+SKIP_BODY=$(cat <<SKIP_EOF
+<!-- FORGE:ARCHITECT -->
+## Architecture Plan — Skipped
+
+**Skipped**: {SKIP_REASON}. No cross-path consistency risk — the builder proceeds with the investigation report + context briefing.
+
+<!-- FORGE:ARCHITECT:COMPLETE -->
+SKIP_EOF
+)
+gh issue comment {NUMBER} {GH_FLAG} --body "$SKIP_BODY" # <!-- allowlist:check-command-side-effects -->
+```
+
+The empty-plan-with-marker changes no downstream behavior — the builder already falls back to the investigation report + contract when the plan is empty (see Integration Point below). The marker only makes the legitimate skip **observable** to the marker-only engine gate. This intentionally does **not** weaken crash detection: a genuinely interrupted architect run still posts no marker at all, so `detectOutcome` still fails-and-escalates it correctly.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgedock",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Autonomous dev pipeline for Claude Code. GitHub as institutional memory — every issue, PR, and annotation survives context resets and makes the next agent smarter.",
   "bin": {
     "forgedock": "bin/forgedock.mjs"

package/scripts/build-knowledge-index.mjs

@@ -48,7 +48,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync, appendFileSync, rea
 import { execSync, spawnSync } from 'child_process';
 import { homedir } from 'os';
 import { dirname, join, resolve } from 'path';
-import { fileURLToPath } from 'url';
+import { fileURLToPath, pathToFileURL } from 'url';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -309,7 +309,11 @@ async function getParser() {
   const parsePath = join(repoRoot, 'packages', 'protocol', 'src', 'parse.js');
 
   try {
-    const mod = await import(parsePath);
+    // On win32 a bare absolute path (C:\...) makes Node parse the drive letter as a
+    // URL scheme (ERR_UNSUPPORTED_ESM_URL_SCHEME). Convert to a file:// URL first —
+    // valid on POSIX too, and matches the import(pathToFileURL(...).href) idiom used
+    // at check-admission-parity.mjs / validate-annotation-node.mjs / check-phase-registry-drift.mjs.
+    const mod = await import(pathToFileURL(parsePath).href);
     _parseAnnotation = mod.parse;
     return _parseAnnotation;
   } catch (e) {

package/scripts/check-spec-markers.sh

@@ -102,6 +102,7 @@ MARKER_REGISTRY="
   DESIGN
   DISPATCHER
   DOSSIER_UPDATED
+  ENGINE_FALLBACK
   FAST_PATH
   FINDING_SOURCE
   FIX_CI

package/scripts/derive-finding-milestone.sh

@@ -126,11 +126,15 @@ fi
 # Portable (non-PCRE) extraction — grep -oP is not supported by Git Bash's
 # grep build on Windows, so use a bash regex + BASH_REMATCH instead of a
 # lookbehind (same convention as scripts/code-index.sh).
+# The leading (^|[^a-z]) group anchors the alternation to a word start so a
+# close-verb embedded in a larger word (e.g. "encloses #1234") cannot match;
+# the body is already lowercased, so [^a-z] is the correct complement class.
+# The extra group shifts the issue-number capture to BASH_REMATCH[3].
 PR_BODY=$(echo "$PR_JSON" | jq -r '.body // empty')
 SOURCE_ISSUE=""
 PR_BODY_LOWER=$(echo "$PR_BODY" | tr '[:upper:]' '[:lower:]')
-if [[ "$PR_BODY_LOWER" =~ (closes|fixes|resolves)[[:space:]]*#([0-9]+) ]]; then
-  SOURCE_ISSUE="${BASH_REMATCH[2]}"
+if [[ "$PR_BODY_LOWER" =~ (^|[^a-z])(closes|fixes|resolves)[[:space:]]*#([0-9]+) ]]; then
+  SOURCE_ISSUE="${BASH_REMATCH[3]}"
 fi
 
 if [ -n "$SOURCE_ISSUE" ]; then
@@ -167,12 +171,18 @@ if [ -n "$MILESTONE_BRANCH" ]; then
   ALL_MILESTONES=$(gh api "repos/${MILESTONES_REPO}/milestones" 2>/dev/null || echo "")
 
   if [ -n "$ALL_MILESTONES" ] && [ "$ALL_MILESTONES" != "[]" ]; then
-    MATCH=$(echo "$ALL_MILESTONES" | jq -r --arg slug "$BRANCH_SLUG" \
-      '.[] | select((.title | ascii_downcase | gsub("[^a-z0-9]+"; "-")) == $slug) | .title' | head -1)
-    if [ -z "$MATCH" ]; then
-      MATCH=$(echo "$ALL_MILESTONES" | jq -r --arg slug "$BRANCH_SLUG" \
-        '.[] | select((.title | ascii_downcase | gsub("[^a-z0-9]+"; "-")) | test($slug)) | .title' | head -1)
-    fi
+    # Single jq invocation: shared `def slugify` replaces the duplicated
+    # downcase/gsub slug transform that previously appeared once per tier
+    # (exact-match, then substring-fallback). Exact match is tried first
+    # (array 1), substring match second (array 2); `first` picks the winner
+    # from the concatenation, preserving the exact-match-wins-over-substring
+    # ordering and the regex semantics of `test($slug)` exactly as before.
+    # <!-- Fixes: forge#2670 -->
+    MATCH=$(echo "$ALL_MILESTONES" | jq -r --arg slug "$BRANCH_SLUG" '
+      def slugify: ascii_downcase | gsub("[^a-z0-9]+"; "-");
+      ([.[] | select((.title | slugify) == $slug)]
+       + [.[] | select((.title | slugify) | test($slug))])
+      | (first.title // empty)')
     if [ -n "$MATCH" ]; then
       echo "$MATCH"
       exit 0