forgedock 1.3.0 → 1.4.0

package/bin/hooks/interactive-engine.mjs

@@ -36,10 +36,10 @@
  * The hook looks for FORGE annotation markers in the transcript's tool
  * results (gh issue comment / gh api calls):
  *
- *   INVESTIGATION:COMPLETE  → phase "investigate" committed
- *   FORGE:CONTEXT           → phase "context" committed
- *   FORGE:ARCHITECT         → phase "architect" committed
- *   FORGE:BUILDER:COMPLETE  → phase "build" committed
+ *   INVESTIGATION:COMPLETE     → phase "investigate" committed
+ *   FORGE:CONTEXT:COMPLETE     → phase "context" committed
+ *   FORGE:ARCHITECT:COMPLETE   → phase "architect" committed
+ *   FORGE:BUILDER:COMPLETE     → phase "build" committed
  *   FORGE:REVIEWER          → phase "review" committed
  *   workflow:merged label   → phase "close" committed (terminal)
  *
@@ -60,6 +60,7 @@ import { fileURLToPath, pathToFileURL } from "url";
 import { dirname, join, resolve } from "path";
 import { existsSync, readFileSync } from "fs";
 import { execFileSync } from "child_process";
+import { PHASE_MARKERS as PHASE_MARKER_REGISTRY } from "../../packages/protocol/src/phases.js";
 
 // ---------------------------------------------------------------------------
 // Bootstrap
@@ -75,18 +76,31 @@ const FORGE_HOME = resolve(__dirname, "..", "..");
 // Maps FORGE annotation markers (found in transcript tool results) to phase IDs.
 // ---------------------------------------------------------------------------
 
+// forge#2378: marker strings are single-sourced from packages/protocol's phase
+// registry (bin/engine/phases.mjs imports the identical registry) — do NOT
+// reintroduce inline "FORGE:..."/"INVESTIGATION:..."/"workflow:merged" literals
+// here. This table previously hand-duplicated those strings and drifted out of
+// sync with the engine's stricter :COMPLETE gate (forge#2375/PR#2395) — sourcing
+// both consumers from one registry makes that class of drift structurally
+// impossible going forward.
+//
+// Require the :COMPLETE suffix — a bare "FORGE:CONTEXT"/"FORGE:ARCHITECT"
+// substring also matches a partial/interrupted annotation (e.g.
+// FORGE:CONTEXT:PARTIAL), which is not actually committed. bin/engine/phases.mjs's
+// architect detectOutcome() requires the identical :COMPLETE marker to consider
+// the phase committed.
 /** @type {Array<{marker: string, phase: string, terminal?: boolean, terminalReason?: string}>} */
 const PHASE_MARKERS = [
-  { marker: "INVESTIGATION:COMPLETE",  phase: "investigate" },
-  { marker: "INVESTIGATION:INVALID",   phase: "investigate", terminal: true, terminalReason: "invalid" },
-  { marker: "DECOMPOSE:YES",           phase: "investigate", terminal: true, terminalReason: "decomposed" },
-  { marker: "FORGE:CONTEXT",           phase: "context" },
-  { marker: "FORGE:ARCHITECT",         phase: "architect" },
-  { marker: "FORGE:BUILDER:COMPLETE",  phase: "build" },
+  { marker: PHASE_MARKER_REGISTRY.investigate.completionMarker, phase: "investigate" },
+  { marker: PHASE_MARKER_REGISTRY.investigate.invalidMarker,    phase: "investigate", terminal: true, terminalReason: "invalid" },
+  { marker: PHASE_MARKER_REGISTRY.investigate.decomposedMarker, phase: "investigate", terminal: true, terminalReason: "decomposed" },
+  { marker: PHASE_MARKER_REGISTRY.context.completionMarker,     phase: "context" },
+  { marker: PHASE_MARKER_REGISTRY.architect.completionMarker,   phase: "architect" },
+  { marker: PHASE_MARKER_REGISTRY.build.completionMarker,       phase: "build" },
   // review phase: PR merged is detected from gh label/state
-  { marker: "FORGE:REVIEWER:MERGED",   phase: "review" },
+  { marker: PHASE_MARKER_REGISTRY.review.completionMarker,      phase: "review" },
   // close phase: issue closed with workflow:merged
-  { marker: "workflow:merged",         phase: "close", terminal: true, terminalReason: "merged" },
+  { marker: PHASE_MARKER_REGISTRY.close.completionLabel,        phase: "close", terminal: true, terminalReason: "merged" },
 ];
 
 /**
@@ -164,13 +178,15 @@ async function main() {
   // missing, block the subagent from completing silently and inject
   // corrective context so the agent knows what to do.
   if (skillInvoked && annotationMissing && phaseId) {
+    // forge#2378: sourced from the same registry as PHASE_MARKERS above — no
+    // second hand-written copy of these marker strings.
     const PHASE_ANNOTATION_MAP = {
-      investigate: "INVESTIGATION:COMPLETE (or INVESTIGATION:INVALID / DECOMPOSE:YES)",
-      context:     "FORGE:CONTEXT",
-      architect:   "FORGE:ARCHITECT",
-      build:       "FORGE:BUILDER:COMPLETE",
-      review:      "FORGE:REVIEWER:MERGED",
-      close:       "workflow:merged label",
+      investigate: `${PHASE_MARKER_REGISTRY.investigate.completionMarker} (or ${PHASE_MARKER_REGISTRY.investigate.invalidMarker} / ${PHASE_MARKER_REGISTRY.investigate.decomposedMarker})`,
+      context:     PHASE_MARKER_REGISTRY.context.completionMarker,
+      architect:   PHASE_MARKER_REGISTRY.architect.completionMarker,
+      build:       PHASE_MARKER_REGISTRY.build.completionMarker,
+      review:      PHASE_MARKER_REGISTRY.review.completionMarker,
+      close:       `${PHASE_MARKER_REGISTRY.close.completionLabel} label`,
     };
     const expected = PHASE_ANNOTATION_MAP[phaseId] || `the ${phaseId} phase annotation`;
     // Output additionalContext JSON (v2.1.163+ SubagentStop format).
@@ -308,6 +324,20 @@ export function parseTranscript(transcriptPath) {
  *   - Scan tool_result entries for gh CLI output containing FORGE annotation markers
  *   - Extract issue number from Skill args or from the skill name context
  *
+ * `outputs` is intentionally always `{}` from this function (forge#2375): earlier
+ * versions matched a bare `"number"` field and a bare `branch[:space]` token against
+ * the full text of every tool_result block, with no scoping to a FORGE-authoritative
+ * source. That regularly matched unrelated JSON (e.g. `gh issue view`'s own `"number"`
+ * field, matching the issue's own number as if it were a PR) or unrelated prose
+ * containing the word "branch", producing corrupt PHASE_COMMIT run-log entries
+ * (observed: `branch:"diff"`, `branch:"writer"`, `branch:"refs"`, `pr:<issue#>`).
+ * Those values were also consumed as a state fallback by
+ * bin/engine/runlog.mjs:deriveState() → bin/engine/phases.mjs:resolveBranch(), so a
+ * corrupt hook-derived value could leak into the engine's own resolution path. The
+ * engine already resolves branch/PR from GitHub ground truth
+ * (bin/engine/phases.mjs:parseBranchFromMarkers(), scoped to the FORGE:BUILDER:COMPLETE
+ * comment — forge#2184) on next pickup, so no replacement extraction is needed here.
+ *
  * @param {object[]} entries
  * @returns {{ issueNumber: number|null, phaseId: string|null, terminalReason: string|null, outputs: object, skillInvoked: boolean, annotationMissing: boolean }}
  */
@@ -352,12 +382,8 @@ export function detectPhase(entries) {
         for (const { marker } of PHASE_MARKERS) {
           if (content.includes(marker)) foundMarkers.add(marker);
         }
-        // Extract PR number if present.
-        const prM = content.match(/"number"\s*:\s*(\d+)/);
-        if (prM) outputs.pr = parseInt(prM[1], 10);
-        // Extract branch from git push output.
-        const branchM = content.match(/(?:refs\/heads\/|branch[:\s]+)([\w\-./]+)/i);
-        if (branchM) outputs.branch = branchM[1];
+        // No PR/branch extraction here (forge#2375) — see the JSDoc above
+        // detectPhase() for why. `outputs` stays empty from this scan.
       }
 
       // Also scan assistant message text blocks for FORGE markers.

package/bin/hooks/pre-tool-use.mjs

@@ -151,17 +151,104 @@ async function getInvariants() {
 /**
  * Allowed label transitions: from → [to, ...]
  * A label not in this map can be added freely (not a workflow: label).
+ *
+ * `workflow:invalid` is reachable from `ready-to-build`, `building`, and
+ * `in-review` (issue #2326) — not just from `investigating` — because
+ * invalidity is not always discovered where the pipeline first labels the
+ * issue "ready to build". A cheap false positive is usually caught during
+ * investigation; a subtler one is only disproved once the architect/build
+ * phase reads the actual code and tests (see #2312: the premise wasn't
+ * disproved until Phase 3C.6 read `bin/tests/engine-crash.test.mjs`).
+ *
+ * These three post-investigation successors are NOT unconditional, though —
+ * see EVIDENCE_REQUIRED_TARGETS below and its enforcement in
+ * checkLabelTransition(). Reaching `workflow:invalid` from any of these
+ * three states requires a posted reversal comment (a second
+ * `FORGE:INVESTIGATOR` comment carrying `**Verdict**: INVALID`) already on
+ * the issue — the state machine still refuses a bare relabel with no
+ * evidence trail. This preserves the original protection (see history below)
+ * while making the terminal state reachable where it is actually discovered.
+ *
+ * History: this map was introduced by #1250/#1513 to stop arbitrary/skipped
+ * label jumps (e.g. investigating → merged in one hop) — it enforces that
+ * every workflow label transition follows the pipeline's real phase order,
+ * with corrective error messages naming the legal next states. Widening a
+ * terminal-reachability edge is safe as long as an equivalent guard (the
+ * evidence precondition) replaces the blanket "not reachable at all" rule
+ * for the specific case this hook was never asked to consider: legitimate,
+ * evidenced invalidation discovered after ready-to-build.
  */
 const LABEL_TRANSITIONS = {
   "workflow:investigating": ["workflow:ready-to-build", "workflow:invalid", "workflow:decomposed"],
-  "workflow:ready-to-build": ["workflow:building"],
-  "workflow:building": ["workflow:in-review", "workflow:ready-to-build"], // retry allowed
-  "workflow:in-review": ["workflow:merged", "workflow:building"],         // review → re-build allowed
+  "workflow:ready-to-build": ["workflow:building", "workflow:invalid"],
+  "workflow:building": ["workflow:in-review", "workflow:ready-to-build", "workflow:invalid"], // retry allowed; evidenced reversal allowed (#2326)
+  "workflow:in-review": ["workflow:merged", "workflow:building", "workflow:invalid"],         // review → re-build allowed; evidenced reversal allowed (#2326)
   "workflow:merged": [],     // terminal — no successors
   "workflow:invalid": [],    // terminal
   "workflow:decomposed": [], // terminal
 };
 
+/**
+ * States from which a transition to `workflow:invalid` requires posted
+ * evidence (a reversal comment), rather than being freely allowed.
+ * `workflow:investigating` is deliberately excluded — invalidation
+ * discovered during initial investigation is the pipeline's normal,
+ * unguarded path (Phase 1D) and needs no additional precondition.
+ */
+const EVIDENCE_REQUIRED_FOR_INVALID_FROM = new Set([
+  "workflow:ready-to-build",
+  "workflow:building",
+  "workflow:in-review",
+]);
+
+/**
+ * `authorAssociation` values (as returned by `gh issue view --json comments`,
+ * which GitHub computes server-side from the commenter's actual repo/org
+ * relationship) that are trusted to post reversal evidence. Deliberately
+ * NOT a hardcoded bot login: the pipeline's own `gh` identity legitimately
+ * rotates (issue #1722 — the primary automation account's token went invalid
+ * mid-batch and a session switched to a maintainer's personal account to keep
+ * working), and a literal-login allowlist would fail closed the next time
+ * identity rotates. Checking the GitHub-computed relationship instead of a
+ * specific account name survives that rotation: whichever account is
+ * authenticated, as long as it is an org member / repo owner / granted
+ * collaborator access, reports one of these three values regardless of which
+ * account it is. Everything else — `CONTRIBUTOR`, `FIRST_TIME_CONTRIBUTOR`,
+ * `NONE`, or a missing/malformed field — is untrusted and must NOT satisfy
+ * the evidence check (issue #2332: this repo is public with no interaction
+ * restrictions, so any free GitHub account can otherwise post a comment
+ * matching the marker + verdict text below).
+ */
+const TRUSTED_REVERSAL_AUTHOR_ASSOCIATIONS = new Set(["OWNER", "MEMBER", "COLLABORATOR"]);
+
+/**
+ * A reversal comment is a `FORGE:INVESTIGATOR` annotation whose verdict is
+ * INVALID — i.e. a second investigation report that supersedes the
+ * original CONFIRMED/PARTIAL verdict with citable evidence (see #2312's
+ * "Investigation Report — CORRECTED" comment for the live example this
+ * pattern is modeled on). Matching on the marker + verdict line only (not
+ * on incident-specific text like issue numbers or the word "CORRECTED")
+ * keeps this a general-purpose evidence check, not a one-off special case.
+ *
+ * In addition to the marker + verdict text, the comment's author must carry
+ * a trusted `authorAssociation` (see TRUSTED_REVERSAL_AUTHOR_ASSOCIATIONS
+ * above, issue #2332) — otherwise any commenter, with no write access to the
+ * repository, could forge the marker text and unlock this transition.
+ *
+ * @param {Array<{body?: string, authorAssociation?: string}>} comments
+ * @returns {boolean}
+ */
+function hasInvalidReversalEvidence(comments) {
+  if (!Array.isArray(comments)) return false;
+  return comments.some((c) => {
+    const body = String((c && c.body) || "");
+    if (!body.includes("FORGE:INVESTIGATOR")) return false;
+    if (!/\*\*Verdict\*\*:\s*INVALID/i.test(body)) return false;
+    const association = String((c && c.authorAssociation) || "").toUpperCase();
+    return TRUSTED_REVERSAL_AUTHOR_ASSOCIATIONS.has(association);
+  });
+}
+
 /** Labels that are never allowed as a PR --base target. */
 const FORBIDDEN_PR_BASES = ["main", "master"];
 
@@ -189,14 +276,20 @@ const WORKFLOW_LABEL_PREFIX = "workflow:";
  * above, which Git Bash still normalizes to) the same whole-drive tree
  * (issue #2113 — PR #2112 review finding SEC-1: `find /c/` was silently
  * ALLOWED because the prior regex had no trailing-slash/dot alternative).
+ * This also includes the trailing-slash dot forms `/./` and `/../` — the
+ * dot alternative did not originally carry the same optional trailing
+ * slash the drive-letter alternative got in #2113, so those two bare
+ * tokens reached the identical whole-drive scan but were wrongly ALLOWED
+ * (issue #2213).
  *
- * Deliberately does NOT match `/c/Users/...`, `/./foo`, `/../foo`, or any
- * other scoped absolute path — only the bare root/drive-mount token itself,
- * optionally followed by exactly one trailing slash (drive-letter case) or
- * standing alone (dot/double-slash case). Case-insensitive on the drive
- * letter only (POSIX paths are otherwise case-sensitive).
+ * Deliberately does NOT match `/c/Users/...`, `/./foo`, `/../foo` (with
+ * anything beyond the trailing slash), or any other scoped absolute path —
+ * only the bare root/drive-mount token itself, optionally followed by
+ * exactly one trailing slash (drive-letter and dot/double-slash cases) or
+ * standing alone. Case-insensitive on the drive letter only (POSIX paths
+ * are otherwise case-sensitive).
  */
-const FIND_ROOT_TOKEN_RE = /^\/(?:[a-zA-Z]\/?|\.{1,2}|\/)?$/;
+const FIND_ROOT_TOKEN_RE = /^\/(?:[a-zA-Z]\/?|\.{1,2}\/?|\/)?$/;
 
 /**
  * Shell metacharacters that can glue a command name to an adjacent token
@@ -503,7 +596,13 @@ function checkPrTarget(command) {
  *
  * Reads the current workflow labels from GitHub via `gh issue view` and
  * validates that the new label is a legal successor in the state machine.
- * Falls back to allow (exit 0) on any gh CLI error so the hook is fail-open.
+ * Falls back to allow (exit 0) on a `gh` CLI error for ordinary transitions,
+ * so the hook stays resilient to transient `gh`/network failures. The one
+ * exception (#2347): when the attempted transition is to `workflow:invalid`
+ * (`mayNeedEvidence`), the same lookup also fetches the reversal-evidence
+ * comments required by the evidence gate below — a `gh` error there fails
+ * *closed* instead, so a transient CLI error can never silently bypass the
+ * evidence gate the way a blanket fail-open would.
  *
  * @param {string} command
  * @returns {string|null} Error message to show, or null if allowed.
@@ -532,11 +631,18 @@ function checkLabelTransition(command) {
   // Extract repo (-R flag) if present.
   const repoFlag = extractFlag(command, "-R") || extractFlag(command, "--repo");
 
-  // Read current labels from GitHub synchronously.
+  // Read current labels from GitHub synchronously. Also fetch comments when
+  // the requested transition is one that requires reversal evidence (see
+  // EVIDENCE_REQUIRED_FOR_INVALID_FROM) — deferred to a single conditional
+  // extra field so the common case (any other transition) stays a
+  // labels-only fetch, unchanged from before #2326.
   let currentWorkflowLabel = null;
+  let comments = null;
+  const mayNeedEvidence = newLabel === "workflow:invalid";
   try {
     const { execFileSync: exec } = _require("child_process");
-    const args = ["issue", "view", issueNum, "--json", "labels"];
+    const fields = mayNeedEvidence ? "labels,comments" : "labels";
+    const args = ["issue", "view", issueNum, "--json", fields];
     if (repoFlag) { args.push("-R", repoFlag); }
     const out = exec("gh", args, {
       encoding: "utf-8",
@@ -553,8 +659,29 @@ function checkLabelTransition(command) {
         currentWorkflowLabel = lbl;
       }
     }
+    if (mayNeedEvidence) {
+      comments = Array.isArray(parsed.comments) ? parsed.comments : [];
+    }
   } catch {
-    return null; // gh CLI error — fail-open
+    if (mayNeedEvidence) {
+      // #2347: the lookup that failed is the same one that would have
+      // fetched the reversal-evidence comments for the workflow:invalid
+      // evidence gate (#2326/#2332). Fail closed here instead of silently
+      // allowing an unverified workflow:invalid transition through.
+      return [
+        `[ForgeDock] BLOCKED: Unable to verify workflow:invalid evidence (gh CLI error).`,
+        ``,
+        `Attempted transition: → "workflow:invalid"`,
+        ``,
+        `This transition requires verifying a posted reversal comment, but the`,
+        `"gh issue view" lookup used to fetch that evidence failed. Failing`,
+        `closed rather than silently bypassing the evidence gate.`,
+        ``,
+        `This is transient, not permanent: retry once "gh issue view ${issueNum}"`,
+        `succeeds again (e.g. after a network blip or rate-limit reset).`,
+      ].join("\n");
+    }
+    return null; // gh CLI error on an ordinary transition — fail-open
   }
 
   if (!currentWorkflowLabel) {
@@ -591,6 +718,35 @@ function checkLabelTransition(command) {
     ].join("\n");
   }
 
+  // Evidence precondition (#2326): reaching workflow:invalid from
+  // ready-to-build/building/in-review is structurally allowed above, but
+  // still gated against *casual* invalidation — a bare relabel with no
+  // paper trail is blocked. Require a posted reversal comment (a second
+  // FORGE:INVESTIGATOR annotation carrying "**Verdict**: INVALID") already
+  // on the issue before allowing the transition through, from a trusted
+  // author (issue #2332 — marker text alone is forgeable by anyone who can
+  // comment on a public issue; see TRUSTED_REVERSAL_AUTHOR_ASSOCIATIONS).
+  if (newLabel === "workflow:invalid" && EVIDENCE_REQUIRED_FOR_INVALID_FROM.has(currentWorkflowLabel)) {
+    if (!hasInvalidReversalEvidence(comments)) {
+      return [
+        `[ForgeDock] BLOCKED: workflow:invalid requires reversal evidence.`,
+        ``,
+        `Current workflow state: "${currentWorkflowLabel}"`,
+        `Attempted transition: → "workflow:invalid"`,
+        ``,
+        `This transition is allowed only when the issue carries a posted reversal:`,
+        `a FORGE:INVESTIGATOR comment with "**Verdict**: INVALID" documenting the`,
+        `evidence that disproved the original premise (see #2312 for the pattern),`,
+        `posted by an author with a trusted authorAssociation (OWNER, MEMBER, or`,
+        `COLLABORATOR — see #2332). A comment matching the marker text from any`,
+        `other commenter does not satisfy this gate.`,
+        ``,
+        `Fix: post the corrected investigation report first (verdict INVALID, with`,
+        `evidence, from a trusted account), then retry this label transition.`,
+      ].join("\n");
+    }
+  }
+
   return null; // valid transition — allow
 }
 

package/bin/journey.mjs

@@ -1101,8 +1101,14 @@ async function removeOrphans(srcDir, destDir) {
     const srcEntries = await readdir(srcDir, { withFileTypes: true });
     srcNames = new Set(srcEntries.map((e) => e.name));
   } catch (err) {
-    if (err.code !== "ENOENT") throw err;
-    // srcDir missing entirely — every dest entry is an orphan.
+    if (err.code !== "ENOENT" && err.code !== "ENOTDIR") throw err;
+    // srcDir missing entirely (ENOENT), or the corresponding source path changed
+    // type and is no longer a directory — e.g. a symlink-to-file replacing what
+    // used to be a real directory (ENOTDIR) — every dest entry is an orphan.
+    // Treating both the same way keeps this a per-path fail-open instead of
+    // letting an uncaught ENOTDIR escape to persistHome()'s single outer catch,
+    // which would otherwise silently skip the *entire* persist for one bad path
+    // (forge#2227).
     srcNames = new Set();
   }
 

package/bin/labels.json

@@ -64,6 +64,11 @@
     "color": "E4E669",
     "description": "Pipeline stalled — requires human intervention. Managed by ForgeDock."
   },
+  {
+    "name": "workflow:engine-error",
+    "color": "B60205",
+    "description": "Pipeline stalled — engine/tool failure (not a genuine human-judgment block). Managed by ForgeDock."
+  },
   {
     "name": "blocked-on-human-merge",
     "color": "006B75",