forgedock 1.8.0 → 1.8.2

package/bin/engine/admission.mjs

@@ -121,6 +121,12 @@ export function canDeduplicateAutomatedAlert(canonical, candidate) {
  *   unit before same-lineage refinements are deferred. `null` disables the bound.
  * @property {number} convergenceWindow - Merged-unit window used to warn when
  *   amplification remains at or above 1.0.
+ * @property {boolean} amplificationBreaker - On-by-default circuit breaker over ALL
+ *   cascade findings (not only same-lineage refinements): when the last
+ *   `convergenceWindow` amplification ratios are all >= 1.0, P3-and-below admission
+ *   pauses (P1/P2 are never affected). Opt out with `amplification_breaker: off`.
+ *   It is deliberately independent of the cascade presets, so lifting the
+ *   generation cap or token budget (`policy: all`) never disables it.
  */
 
 /**
@@ -179,6 +185,19 @@ export function parseOptionalPositiveNumber(raw) {
   };
 }
 
+/**
+ * Parse an on/off toggle that defaults to ON. Accepts booleans and the strings
+ * "on"/"off"/"true"/"false". An unrecognized value keeps the safe default (on).
+ */
+export function parseOnByDefaultToggle(raw) {
+  if (raw === undefined || raw === null || raw === "" || raw === "null") return { value: true, warning: null };
+  if (typeof raw === "boolean") return { value: raw, warning: null };
+  const t = String(raw).trim().toLowerCase();
+  if (t === "on" || t === "true") return { value: true, warning: null };
+  if (t === "off" || t === "false") return { value: false, warning: null };
+  return { value: true, warning: `not on/off ("${raw}") — keeping the breaker on` };
+}
+
 /**
  * Parse a raw config value that may be a positive integer, the literal
  * string "unlimited" (case-insensitive), or absent/invalid. Mirrors the
@@ -229,6 +248,7 @@ export function parseIntOrUnlimited(raw, fallback) {
  * @param {boolean} [config.p3_same_file_defer]
  * @param {number|string} [config.max_amplification]
  * @param {number|string} [config.convergence_window]
+ * @param {boolean|string} [config.amplification_breaker] - "on" (default) | "off".
  * @param {number|string} [legacyTokenBudgetPerBatch] - Deprecated-alias fallback:
  *   `pipeline.token_budget_per_batch`, read when `config.token_budget` is absent
  *   so existing configs keep working unchanged (see forge#1858).
@@ -308,6 +328,11 @@ export function resolveCascadePolicy(config = {}, legacyTokenBudgetPerBatch) {
     );
   }
 
+  const amplificationBreaker = parseOnByDefaultToggle(config.amplification_breaker);
+  if (amplificationBreaker.warning) {
+    warnings.push(`orchestration.cascade.amplification_breaker ${amplificationBreaker.warning}`);
+  }
+
   // Both-uncapped notice: neither generation depth nor token spend is bounded this
   // run. This is never a preset default (no preset in CASCADE_PRESETS sets both to
   // UNLIMITED... except "all", which does so deliberately) — surface it loudly so an
@@ -332,6 +357,7 @@ export function resolveCascadePolicy(config = {}, legacyTokenBudgetPerBatch) {
       p3SameFileDefer,
       maxAmplification: maxAmplification.value,
       convergenceWindow: convergenceWindow.value === UNLIMITED ? 3 : convergenceWindow.value,
+      amplificationBreaker: amplificationBreaker.value,
     },
     policyName,
     bothUncapped,
@@ -387,6 +413,26 @@ export function evaluateAmplification(mergedUnits, findingsSpawned, policy) {
   };
 }
 
+/**
+ * Evaluate the on-by-default amplification breaker. Counts every cascade finding
+ * (the ratio history is findings spawned / merged units, not refinement-only).
+ * Trips when the latest `convergenceWindow` observations are all >= 1.0; releases
+ * as soon as the newest observation falls below 1.0.
+ *
+ * @param {number[]} ratioHistory - Amplification ratios, oldest first.
+ * @param {CascadePolicy} policy
+ * @returns {{ tripped: boolean, ratio: number }}
+ */
+export function evaluateAmplificationBreaker(ratioHistory, policy) {
+  const history = Array.isArray(ratioHistory) ? ratioHistory : [];
+  const ratio = history.length ? history[history.length - 1] : 0;
+  if (!policy.amplificationBreaker || history.length < policy.convergenceWindow) {
+    return { tripped: false, ratio };
+  }
+  const recent = history.slice(-policy.convergenceWindow);
+  return { tripped: recent.every((r) => r >= 1), ratio };
+}
+
 /**
  * Evaluate the Step 4C rule chain for a single cascade-spawned finding.
  * Mirrors `commands/orchestrate/phase-4-execution.md` Step 4C's "Evaluation
@@ -405,6 +451,8 @@ export function evaluateAmplification(mergedUnits, findingsSpawned, policy) {
  * @param {boolean} finding.sameFileAsBatch
  * @param {boolean} finding.batchFullyGated
  * @param {number} finding.projectedTokenSpend
+ * @param {boolean} [finding.amplificationBreakerTripped] - Result of
+ *   `evaluateAmplificationBreaker` for this batch (rule 6).
  * @param {CascadePolicy} policy
  * @returns {{ admit: boolean, reason: string|null }}
  */
@@ -418,7 +466,7 @@ export function evaluateCascadeFinding(finding, policy) {
       reason: `generation ${finding.generation} exceeds orchestration.cascade.max_generation (${policy.maxGeneration})`,
     };
   }
-  if (finding.priority === "P1" || finding.priority === "P2") {
+  if (finding.priority === "P0" || finding.priority === "P1" || finding.priority === "P2") {
     return { admit: true, reason: null };
   }
   if (policy.keywordHeuristic && /comment|typo/i.test(finding.title || "")) {
@@ -430,6 +478,14 @@ export function evaluateCascadeFinding(finding, policy) {
   if (!admitsTokenSpend(finding.projectedTokenSpend, policy)) {
     return { admit: false, reason: `per-batch token budget exhausted (orchestration.cascade.token_budget=${policy.tokenBudget})` };
   }
+  // Rule 6 (forge#3060) is evaluated last, mirroring the bash chain. It only gates P3-and-below:
+  // P0/P1/P2 already returned above.
+  if (policy.amplificationBreaker && finding.amplificationBreakerTripped && /^P[3-9]$/.test(finding.priority || "")) {
+    return {
+      admit: false,
+      reason: "amplification breaker tripped — P3 admission paused (routed to P3 batches / completion sweep)",
+    };
+  }
   return { admit: true, reason: null };
 }
 

package/bin/engine/admission.test.mjs

@@ -13,6 +13,7 @@ import {
   evaluateCascadeFinding,
   classifyBatchSafety,
   evaluateAmplification,
+  evaluateAmplificationBreaker,
   batchExclusionReason,
   planP3BatchGroups,
   canDeduplicateAutomatedAlert,
@@ -122,6 +123,7 @@ describe("resolveCascadePolicy — presets", () => {
       ...CASCADE_PRESETS.balanced,
       maxAmplification: null,
       convergenceWindow: 3,
+      amplificationBreaker: true,
     });
     assert.deepEqual(warnings, []);
   });
@@ -157,6 +159,7 @@ describe("resolveCascadePolicy — presets", () => {
       ...CASCADE_PRESETS.balanced,
       maxAmplification: null,
       convergenceWindow: 3,
+      amplificationBreaker: true,
     });
     assert.equal(warnings.length, 1);
     assert.match(warnings[0], /not one of/);
@@ -219,6 +222,63 @@ describe("evaluateAmplification", () => {
   });
 });
 
+describe("evaluateAmplificationBreaker (forge#3060)", () => {
+  it("is on by default, including under policy: all", () => {
+    assert.equal(resolveCascadePolicy().policy.amplificationBreaker, true);
+    assert.equal(resolveCascadePolicy({ policy: "all" }).policy.amplificationBreaker, true);
+  });
+
+  it("opts out with off/false and keeps on for garbage with a warning", () => {
+    assert.equal(resolveCascadePolicy({ amplification_breaker: "off" }).policy.amplificationBreaker, false);
+    assert.equal(resolveCascadePolicy({ amplification_breaker: false }).policy.amplificationBreaker, false);
+    const r = resolveCascadePolicy({ amplification_breaker: "maybe" });
+    assert.equal(r.policy.amplificationBreaker, true);
+    assert.match(r.warnings[0], /amplification_breaker/);
+  });
+
+  it("trips only when the latest convergence_window ratios are all >= 1.0", () => {
+    const { policy } = resolveCascadePolicy();
+    assert.equal(evaluateAmplificationBreaker([1.5, 1.4], policy).tripped, false);
+    assert.equal(evaluateAmplificationBreaker([1.5, 1.4, 1.35], policy).tripped, true);
+    assert.equal(evaluateAmplificationBreaker([0.5, 1.4, 1.35], policy).tripped, false);
+    assert.equal(evaluateAmplificationBreaker([1.5, 1.4, 1.35, 0.9], policy).tripped, false);
+  });
+
+  it("never trips when opted out", () => {
+    const { policy } = resolveCascadePolicy({ amplification_breaker: "off" });
+    assert.equal(evaluateAmplificationBreaker([2, 2, 2], policy).tripped, false);
+  });
+
+  it("pauses P3 admission but never P1/P2, and ignores same-lineage max_amplification", () => {
+    const { policy } = resolveCascadePolicy({ policy: "all" });
+    const base = { generation: 1, title: "x", sameFileAsBatch: false, batchFullyGated: false, projectedTokenSpend: 0, amplificationBreakerTripped: true };
+    assert.equal(evaluateCascadeFinding({ ...base, priority: "P3" }, policy).admit, false);
+    assert.match(evaluateCascadeFinding({ ...base, priority: "P3" }, policy).reason, /amplification breaker/);
+    assert.equal(evaluateCascadeFinding({ ...base, priority: "P2" }, policy).admit, true);
+    assert.equal(evaluateCascadeFinding({ ...base, priority: "P1" }, policy).admit, true);
+    assert.equal(evaluateCascadeFinding({ ...base, priority: "P0" }, policy).admit, true);
+    assert.equal(evaluateCascadeFinding({ ...base, priority: "P3", amplificationBreakerTripped: false }, policy).admit, true);
+  });
+
+  it("rule 6 never gates untriaged (empty/unknown) priorities", () => {
+    const { policy } = resolveCascadePolicy();
+    const f = { generation: 1, priority: "", title: "x", sameFileAsBatch: false, batchFullyGated: false, projectedTokenSpend: 0, amplificationBreakerTripped: true };
+    assert.equal(evaluateCascadeFinding(f, policy).admit, true);
+  });
+
+  it("rule 6 is evaluated last: a tripped typo P3 reports the keyword reason first under balanced", () => {
+    const { policy } = resolveCascadePolicy();
+    const f = { generation: 1, priority: "P3", title: "fix typo", sameFileAsBatch: false, batchFullyGated: false, projectedTokenSpend: 0, amplificationBreakerTripped: true };
+    assert.match(evaluateCascadeFinding(f, policy).reason, /comment\/typo/);
+  });
+
+  it("existing numeric max_amplification configs keep working alongside the breaker", () => {
+    const { policy } = resolveCascadePolicy({ max_amplification: 1.5 });
+    assert.equal(policy.maxAmplification, 1.5);
+    assert.equal(policy.amplificationBreaker, true);
+  });
+});
+
 describe("resolveCascadePolicy — token_budget deprecated-alias fallback", () => {
   it("falls back to legacy pipeline.token_budget_per_batch when orchestration.cascade.token_budget is absent", () => {
     const { policy } = resolveCascadePolicy({ policy: "balanced" }, 300000);

package/commands/analytics.md

@@ -7,6 +7,8 @@ install: extras
 
 # /analytics — Production Analytics Audit & Issue Generator
 
+> **Skill names**: `{FORGE_SKILL_PREFIX}` is `forgedock:` (plugin install) or empty (`install.sh`), resolved once per run by `commands/work-on.md` § Skill Name Resolution. If the skill is not found under either name, STOP and report "skill not found" — never run the phase inline.
+
 You are the analytics orchestrator. Pull data from ALL available analytics platforms (Google Search Console, Bing Webmaster, Microsoft Clarity, Umami, Cloudflare, Google Analytics 4), cross-reference the findings, generate actionable insights, and decompose them into concrete GitHub issues that the `/work-on` pipeline can pick up.
 
 **You have access to ALL tools** — MCP tools for GSC/Clarity/Stripe, Bash for Umami/Cloudflare/Bing APIs, Agent tool for parallel data collection.
@@ -728,7 +730,7 @@ BODY_EOF
 ```
 
 ```
-Skill(skill="issue", args="--title \"{type}: {action title}\" --body-file \"$ANALYTICS_BODY_FILE\" --label \"{priority}\" --label \"{category_label_1}\" --label \"{category_label_2}\"")
+Skill(skill="{FORGE_SKILL_PREFIX}issue", args="--title \"{type}: {action title}\" --body-file \"$ANALYTICS_BODY_FILE\" --label \"{priority}\" --label \"{category_label_1}\" --label \"{category_label_2}\"")
 ```
 
 `{priority}`, `{category_label_1}`, and `{category_label_2}` are each passed as their own `--label` flag — `/issue`'s programmatic mode does not comma-split a single `--label` value. Resolve `{category_label_1}`/`{category_label_2}` from the label mapping below: split each mapping's comma-separated value into one label per placeholder. When a category maps to only one label, omit the `--label "{category_label_2}"` flag entirely (do not pass an empty string).

package/commands/audit-agents.md

@@ -8,6 +8,8 @@ install: extras
 
 # /audit-agents — Agent Output Auditor
 
+> **Skill names**: `{FORGE_SKILL_PREFIX}` is `forgedock:` (plugin install) or empty (`install.sh`), resolved once per run by `commands/work-on.md` § Skill Name Resolution. If the skill is not found under either name, STOP and report "skill not found" — never run the phase inline.
+
 **Input**: $ARGUMENTS
 
 ## Purpose
@@ -511,7 +513,7 @@ N/A — this is a running log issue, not a code change.
 This issue is a running log of persisted `/audit-agents` summaries. Each comment contains one session's efficiency metrics. Do not close this issue — `/pipeline-health` Phase 2K queries it to aggregate orchestration efficiency trends.
 EOF
 
-  Skill(skill="issue", args="--title \"Orchestration Metrics — Running Log\" --body-file \"$TRACKING_BODY_FILE\" --label \"orchestration-metrics\"")
+  Skill(skill="{FORGE_SKILL_PREFIX}issue", args="--title \"Orchestration Metrics — Running Log\" --body-file \"$TRACKING_BODY_FILE\" --label \"orchestration-metrics\"")
 
   # /issue's programmatic mode does not print a structured return value — re-query
   # by label to recover the newly created issue number.

package/commands/audit.md

@@ -8,6 +8,8 @@ install: extras
 
 # /audit — Pipeline Failure Trace & Self-Healing Issue
 
+> **Skill names**: `{FORGE_SKILL_PREFIX}` is `forgedock:` (plugin install) or empty (`install.sh`), resolved once per run by `commands/work-on.md` § Skill Name Resolution. If the skill is not found under either name, STOP and report "skill not found" — never run the phase inline.
+
 **Input**: $ARGUMENTS
 
 You are Forge's post-mortem auditor. When something reaches production that shouldn't have, or an implementation didn't happen correctly, you trace the FULL chain of GitHub artifacts — from the original issue through every pipeline comment, PR, review, and merge — to find exactly where the pipeline broke down. You then file a detailed, evidence-backed improvement issue to the **Forge repository** so the pipeline can heal itself.
@@ -240,16 +242,16 @@ Classify where the breakdown occurred. Use these categories:
 
 | Failure Point | Description | Fix Target |
 |---------------|-------------|------------|
-| **INVESTIGATION** | Wrong verdict, missed scope, insufficient analysis | `commands/work-on.md` Phase 1 |
-| **DECOMPOSITION** | Should have decomposed but didn't, or decomposed wrong | `commands/work-on.md` Phase 2 |
-| **CONTRACT** | Wrong deliverables, missing acceptance criteria | `commands/work-on.md` Phase 3C |
-| **CONTEXT** | Missed relevant prior work, bug patterns, or related code | `commands/work-on.md` Phase 3C.5 |
-| **ARCHITECT** | Missed code paths, wrong implementation plan | `commands/work-on.md` Phase 3C.6 |
-| **IMPLEMENTATION** | Code written incorrectly, incomplete, wrong approach | `commands/work-on.md` Phase 3F, builder rules |
+| **INVESTIGATION** | Wrong verdict, missed scope, insufficient analysis | `commands/work-on/investigate.md` |
+| **DECOMPOSITION** | Should have decomposed but didn't, or decomposed wrong | `commands/work-on/decompose.md` |
+| **CONTRACT** | Wrong deliverables, missing acceptance criteria | `commands/work-on/build.md` (B2 Contract) |
+| **CONTEXT** | Missed relevant prior work, bug patterns, or related code | `commands/work-on/build/context.md` |
+| **ARCHITECT** | Missed code paths, wrong implementation plan | `commands/work-on/build/architect.md` |
+| **IMPLEMENTATION** | Code written incorrectly, incomplete, wrong approach | `commands/work-on/build/implement.md` (I3 rules) |
 | **QUALITY_GATE** | Should have caught this defect class but didn't | `commands/quality-gate.md` |
 | **REVIEW** | Review agents missed the issue, or wrong agents were triggered | `commands/review-pr.md`, `commands/review-pr-agents.md` |
 | **REVIEW_FALSE_NEG** | Review agent looked at the right area but didn't flag the problem | `commands/review-pr-agents.md` (agent template) |
-| **MERGE_POLICY** | Merged despite signals that should have blocked | `commands/work-on.md` Phase 5 |
+| **MERGE_POLICY** | Merged despite signals that should have blocked | `commands/work-on/review.md` + `commands/review-pr.md` Phase 8 |
 | **DEPLOY_GATE** | Deploy-info should have flagged risk but didn't | `commands/deploy-info.md` |
 | **ORCHESTRATION** | Wave ordering wrong, dependency missed, stall | `commands/orchestrate.md` |
 | **ISSUE_SPEC** | Original issue was ambiguous/incomplete — pipeline followed it correctly but the spec was wrong | Not a pipeline fix — note for process improvement |
@@ -384,7 +386,7 @@ EOF
 ```
 
 ```
-Skill(skill="issue", args="--title \"$AUDIT_TITLE\" --body-file \"$AUDIT_BODY_FILE\" --label \"{LABEL_1}\" --label \"{LABEL_2}\" --label \"{LABEL_3}\"")
+Skill(skill="{FORGE_SKILL_PREFIX}issue", args="--title \"$AUDIT_TITLE\" --body-file \"$AUDIT_BODY_FILE\" --label \"{LABEL_1}\" --label \"{LABEL_2}\" --label \"{LABEL_3}\"")
 ```
 
 `{LABELS}` from the table in 4A (e.g. `P1,audit-finding,bug`) is split into one `--label` flag per label (`{LABEL_1}`, `{LABEL_2}`, `{LABEL_3}`) — `/issue`'s programmatic mode does not comma-split a single `--label` value. If `/issue` stops on dedup (near-duplicate or usage error, per the note above), do not fall back to a raw `gh issue create` — comment on the existing issue with the new evidence instead.

package/commands/autopilot.md

@@ -8,6 +8,8 @@ install: extras
 
 # /autopilot — Autonomous Deploy Loop
 
+> **Skill names**: `{FORGE_SKILL_PREFIX}` is `forgedock:` (plugin install) or empty (`install.sh`), resolved once per run by `commands/work-on.md` § Skill Name Resolution. If the skill is not found under either name, STOP and report "skill not found" — never run the phase inline.
+
 **Input**: $ARGUMENTS (default: full autonomous loop until zero open issues remain)
 
 **Config variables used by this command** (set in `forge.yaml`):
@@ -160,7 +162,7 @@ This issue is the rolling log for `/autopilot` cycle annotations. Each cycle app
 OPS_EOF
     # Route through the /issue create-hook (canonical dedup + body validation) instead of
     # a raw `gh issue create`. See commands/issue.md Programmatic Invocation Contract.
-    Skill(skill="issue", args="--title \"ops: autopilot cycle log\" --body-file \"$OPS_BODY_TMPFILE\" --label \"$AUTOPILOT_OPS_LABEL\"")
+    Skill(skill="{FORGE_SKILL_PREFIX}issue", args="--title \"ops: autopilot cycle log\" --body-file \"$OPS_BODY_TMPFILE\" --label \"$AUTOPILOT_OPS_LABEL\"")
     rm -f "$OPS_BODY_TMPFILE"
     trap - EXIT
     OPS_ISSUE_NUMBER=$(gh issue list $GH_FLAG \
@@ -403,7 +405,7 @@ RECOVER_ORPHANS_AVAILABLE=$(ls ~/.claude/commands/recover-orphans.md 2>/dev/null
 if [ "$INFLIGHT_ISSUES" -gt 0 ]; then
   if [ "$RECOVER_ORPHANS_AVAILABLE" = "true" ] && [ "$DRY_RUN" = "false" ]; then
     echo "Recovering $INFLIGHT_ISSUES orphaned pipeline issue(s)..."
-    Skill("recover-orphans", args="")
+    Skill("{FORGE_SKILL_PREFIX}recover-orphans", args="")
   elif [ "$DRY_RUN" = "true" ]; then
     echo "[DRY-RUN] Would invoke: Skill(recover-orphans)"
   else
@@ -462,7 +464,7 @@ CLEANUP_AVAILABLE=$(ls ~/.claude/commands/cleanup.md 2>/dev/null && echo "true"
 if [ "$DRY_RUN" = "false" ]; then
   if [ "$CLEANUP_AVAILABLE" = "true" ]; then
     echo "Running label hygiene sweep via /cleanup..."
-    Skill("cleanup", args="labels")
+    Skill("{FORGE_SKILL_PREFIX}cleanup", args="labels")
     CLEANUP_LABELS_FIXED=1  # /cleanup ran; detailed counts are in its own output
   else
     echo "INFO: /cleanup not installed (extras tier) — skipping label hygiene sweep. Install with: npx forgedock install --extras"
@@ -594,7 +596,7 @@ ISSUE_BODY_EOF
   # Route through the /issue create-hook (canonical dedup + body validation) instead of
   # a raw `gh issue create`. If /issue finds a near-duplicate, it reports it and does not
   # create — NEW_NUMBER will come back empty from the lookup below.
-  Skill(skill="issue", args="--title \"$FINDING_TITLE\" --body-file \"$BODY_TMPFILE\" --label P2 --label bug")
+  Skill(skill="{FORGE_SKILL_PREFIX}issue", args="--title \"$FINDING_TITLE\" --body-file \"$BODY_TMPFILE\" --label P2 --label bug")
 
   rm -f "$BODY_TMPFILE"
   trap - EXIT
@@ -822,7 +824,7 @@ To approve: remove \`needs-human\` label from #${ISSUE_NUM} and re-run \`/autopi
               2>/dev/null | grep -q true; then
             echo "  #$ISSUE_NUM ⟳ stalled at workflow:in-review (PR merged) — resuming via recover-orphans"
             if [ "$RECOVER_ORPHANS_AVAILABLE" = "true" ]; then
-              Skill("recover-orphans", args="--issue $ISSUE_NUM")
+              Skill("{FORGE_SKILL_PREFIX}recover-orphans", args="--issue $ISSUE_NUM")
             else
               echo "  WARNING: recover-orphans not installed — cannot auto-resume #$ISSUE_NUM"
               STALLED_ISSUES+=("$ISSUE_NUM")
@@ -858,7 +860,7 @@ To approve: remove \`needs-human\` label from #${ISSUE_NUM} and re-run \`/autopi
         2>/dev/null || echo '')
       for N in $PRE_DISPATCH_ISSUES; do DISPATCHED_ISSUES+=("$N"); done
 
-      Skill("orchestrate", args="fast-lane --auto")
+      Skill("{FORGE_SKILL_PREFIX}orchestrate", args="fast-lane --auto")
 
       # Terminal-state verification after orchestrate (fallback path).
       # Re-query GitHub state for each pre-dispatch issue.
@@ -894,7 +896,7 @@ To approve: remove \`needs-human\` label from #${ISSUE_NUM} and re-run \`/autopi
   if [ "$STAGING_AHEAD_NOW" -gt 0 ]; then
     echo "staging is $STAGING_AHEAD_NOW commit(s) ahead — deploying via /deploy-pr..."
     if [ "$DRY_RUN" = "false" ]; then
-      DEPLOY_RESULT=$(Skill("deploy-pr", args="staging"))
+      DEPLOY_RESULT=$(Skill("{FORGE_SKILL_PREFIX}deploy-pr", args="staging"))
       # Parse structured JSON result from deploy-pr
       DEPLOY_STATUS=$(echo "$DEPLOY_RESULT" | jq -r '.status // empty' 2>/dev/null || echo '')
       [ -z "$DEPLOY_STATUS" ] && DEPLOY_STATUS=$(echo "$DEPLOY_RESULT" | grep -oE '"status":"[^"]*"' | grep -oE '"[^"]*"$' | tr -d '"' || echo 'unknown')
@@ -909,7 +911,7 @@ To approve: remove \`needs-human\` label from #${ISSUE_NUM} and re-run \`/autopi
 
   # Step 3: Recover any newly orphaned issues before next iteration
   if [ "$RECOVER_ORPHANS_AVAILABLE" = "true" ] && [ "$DRY_RUN" = "false" ]; then
-    Skill("recover-orphans", args="--since 2")
+    Skill("{FORGE_SKILL_PREFIX}recover-orphans", args="--since 2")
   elif [ "$DRY_RUN" = "true" ]; then
     echo "[DRY-RUN] Would invoke: Skill(recover-orphans, --since 2)"
   fi
@@ -1083,7 +1085,7 @@ To approve: remove \`needs-human\` label from #${ISSUE_NUM} and re-run \`/autopi
           elif echo "$ISSUE_LABEL_STR" | grep -q 'workflow:in-review'; then
             echo "  #$ISSUE_NUM ⟳ stalled at workflow:in-review — resuming via recover-orphans"
             if [ "$RECOVER_ORPHANS_AVAILABLE" = "true" ]; then
-              Skill("recover-orphans", args="--issue $ISSUE_NUM")
+              Skill("{FORGE_SKILL_PREFIX}recover-orphans", args="--issue $ISSUE_NUM")
             else
               echo "  WARNING: recover-orphans not installed — cannot auto-resume #$ISSUE_NUM"
               STALLED_ISSUES+=("$ISSUE_NUM")
@@ -1112,7 +1114,7 @@ To approve: remove \`needs-human\` label from #${ISSUE_NUM} and re-run \`/autopi
           2>/dev/null || echo '')
         for N in $MS_PRE_DISPATCH; do DISPATCHED_ISSUES+=("$N"); done
 
-        Skill("orchestrate", args="milestone $MS_SLUG --auto")
+        Skill("{FORGE_SKILL_PREFIX}orchestrate", args="milestone $MS_SLUG --auto")
 
         # Terminal-state verification after orchestrate fallback.
         echo "Verifying terminal state for $( echo "$MS_PRE_DISPATCH" | wc -w | tr -d ' ') dispatched milestone issue(s) (orchestrate path)..."
@@ -1150,7 +1152,7 @@ To approve: remove \`needs-human\` label from #${ISSUE_NUM} and re-run \`/autopi
   if [ "$MILESTONE_BRANCH_EXISTS" = "true" ]; then
     echo "Shipping $MILESTONE_BRANCH → staging..."
     if [ "$DRY_RUN" = "false" ]; then
-      MS_RESULT=$(Skill("deploy-pr", args="$MILESTONE_BRANCH"))
+      MS_RESULT=$(Skill("{FORGE_SKILL_PREFIX}deploy-pr", args="$MILESTONE_BRANCH"))
       MS_STATUS=$(echo "$MS_RESULT" | jq -r '.status // empty' 2>/dev/null || echo '')
       [ -z "$MS_STATUS" ] && MS_STATUS=$(echo "$MS_RESULT" | grep -oE '"status":"[^"]*"' | grep -oE '"[^"]*"$' | tr -d '"' || echo 'unknown')
       echo "Milestone ship status: $MS_STATUS"
@@ -1163,7 +1165,7 @@ To approve: remove \`needs-human\` label from #${ISSUE_NUM} and re-run \`/autopi
         STAGING_AHEAD_MS=$(git rev-list --count "origin/${DEFAULT_BRANCH}..origin/${STAGING_BRANCH}" 2>/dev/null || echo '0')
         if [ "$STAGING_AHEAD_MS" -gt 0 ]; then
           echo "Milestone merged to staging — deploying staging → $DEFAULT_BRANCH..."
-          MAIN_RESULT=$(Skill("deploy-pr", args="staging"))
+          MAIN_RESULT=$(Skill("{FORGE_SKILL_PREFIX}deploy-pr", args="staging"))
           MAIN_STATUS=$(echo "$MAIN_RESULT" | jq -r '.status // empty' 2>/dev/null || echo 'unknown')
           echo "Main deploy status: $MAIN_STATUS"
           [ "$MAIN_STATUS" = "merged" ] && FAST_LANE_DEPLOYS=$((FAST_LANE_DEPLOYS + 1))
@@ -1377,7 +1379,7 @@ META_EOF
           # Route through the /issue create-hook (canonical dedup + body validation) instead
           # of a raw `gh issue create`. The EXISTING_META search above already guards against
           # re-creating for the same pattern; /issue's own dedup is an additional safety net.
-          Skill(skill="issue", args="--title \"$META_TITLE\" --body-file \"$META_BODY_TMPFILE\" --label priority:P2")
+          Skill(skill="{FORGE_SKILL_PREFIX}issue", args="--title \"$META_TITLE\" --body-file \"$META_BODY_TMPFILE\" --label priority:P2")
           rm -f "$META_BODY_TMPFILE"
           trap - EXIT
           META_NEW_NUMBER=$(gh issue list $GH_FLAG \
@@ -1591,7 +1593,7 @@ Rules are listed in **precedence order** — when two rules appear to conflict,
 
 **Rule 8: deploy-pr result is authoritative** — if status is not "merged", do not assume the deploy succeeded. Log and continue the loop.
 
-**Rule 9: Terminal-state verification is mandatory after every dispatch batch.** After every `forgedock run-issue … wait` block or `Skill(orchestrate)` call, autopilot MUST query the actual GitHub label state for each dispatched issue. An issue whose process exits 0 but whose GitHub label is still `workflow:in-review` or `workflow:building` is NOT done — the close phase may have been interrupted. Stalls at `workflow:in-review` with a merged PR are the known recoverable class; autopilot resumes them via `Skill("recover-orphans", args="--issue N")` once before recording them as stalled. The Phase 4 report MUST emit a per-issue disposition table sourced from these GitHub-verified states — self-reported sub-process success is not sufficient. <!-- Added: forge#1751 -->
+**Rule 9: Terminal-state verification is mandatory after every dispatch batch.** After every `forgedock run-issue … wait` block or `Skill(orchestrate)` call, autopilot MUST query the actual GitHub label state for each dispatched issue. An issue whose process exits 0 but whose GitHub label is still `workflow:in-review` or `workflow:building` is NOT done — the close phase may have been interrupted. Stalls at `workflow:in-review` with a merged PR are the known recoverable class; autopilot resumes them via `Skill("{FORGE_SKILL_PREFIX}recover-orphans", args="--issue N")` once before recording them as stalled. The Phase 4 report MUST emit a per-issue disposition table sourced from these GitHub-verified states — self-reported sub-process success is not sufficient. <!-- Added: forge#1751 -->
 
 **Headless / unattended operation**: `/autopilot` has no human checkpoint and never waits for user input. When invoked via `/loop 4h /autopilot` or any other unattended runner, it runs to completion and exits. Human escalation is exclusively via the `needs-human` label (Rule 2 above) — autopilot surfaces `needs-human` issues in the recon report but never stalls waiting for a response. There is no "Phase 4B confirm before fixing" gate in the current design; that checkpoint was intentionally removed in the #1673 rewrite. If a future design adds a confirmation gate, it must be guarded by both Rule 0 (dry-run) and Rule 2 (needs-human) to remain safe.
 

package/commands/ci-audit.md

@@ -8,6 +8,8 @@ install: extras
 
 # /ci-audit — Stack-Aware CI Gap Detection
 
+> **Skill names**: `{FORGE_SKILL_PREFIX}` is `forgedock:` (plugin install) or empty (`install.sh`), resolved once per run by `commands/work-on.md` § Skill Name Resolution. If the skill is not found under either name, STOP and report "skill not found" — never run the phase inline.
+
 **Input**: $ARGUMENTS
 
 You are the CI hygiene auditor. Given a project's declared tech stack (from `forge.yaml`), determine what config validation tools exist for each stack component and audit whether the project's GitHub Actions workflows include those validation steps. File GitHub issues for any gaps found.
@@ -370,7 +372,7 @@ ${VERSION_NOTE}
             # be unsafe to re-embed into a Skill args string.
             CI_GAP_BODY_FILE=$(mktemp)
             printf '%s' "$ISSUE_BODY" > "$CI_GAP_BODY_FILE"
-            Skill(skill="issue", args="--title \"ci($tool): add structural config validation step to CI pipeline\" --body-file \"$CI_GAP_BODY_FILE\" --label \"bug\" --label \"P2\" --label \"audit-finding\"")
+            Skill(skill="{FORGE_SKILL_PREFIX}issue", args="--title \"ci($tool): add structural config validation step to CI pipeline\" --body-file \"$CI_GAP_BODY_FILE\" --label \"bug\" --label \"P2\" --label \"audit-finding\"")
         fi
     fi
 done
@@ -414,7 +416,7 @@ The project has a \`$tool\` validation step in CI, but it only runs in the deplo
         # re-embed into a Skill args string.
         CI_PLACEMENT_BODY_FILE=$(mktemp)
         printf '%s' "$ISSUE_BODY" > "$CI_PLACEMENT_BODY_FILE"
-        Skill(skill="issue", args="--title \"ci($tool): move config validation to PR-time CI workflow\" --body-file \"$CI_PLACEMENT_BODY_FILE\" --label \"bug\" --label \"P3\" --label \"audit-finding\"")
+        Skill(skill="{FORGE_SKILL_PREFIX}issue", args="--title \"ci($tool): move config validation to PR-time CI workflow\" --body-file \"$CI_PLACEMENT_BODY_FILE\" --label \"bug\" --label \"P3\" --label \"audit-finding\"")
     fi
 done
 ```

package/commands/cleanup.md

@@ -267,7 +267,7 @@ echo "Removed: $WORKTREE_PATH ($BRANCH_NAME)"
 Delete remote `fix/` and `feat/` branches whose PR has merged — using **GitHub PR state as the source of truth**, not local git ancestry.
 
 **Why not `git branch -r --merged {STAGING_BRANCH}`**: an ancestry check only catches branches whose tip commit is reachable from `{STAGING_BRANCH}`. This misses two common cases:
-- **Feature-lane branches merged into a milestone branch.** Per `work-on.md` Phase 3E, milestone issues branch from and PR into `origin/milestone/{slug}`, not `{STAGING_BRANCH}`. Once such a branch's own PR merges into the milestone branch, it's fully absorbed and safe to delete — but it won't show up as "merged into staging" until the milestone itself ships (which may be days later, or never, if abandoned). This is the dominant cause of `feat/*` branches accumulating for a milestone/feature cluster.
+- **Feature-lane branches merged into a milestone branch.** Per `work-on/build.md` (B1 worktree), milestone issues branch from and PR into `origin/milestone/{slug}`, not `{STAGING_BRANCH}`. Once such a branch's own PR merges into the milestone branch, it's fully absorbed and safe to delete — but it won't show up as "merged into staging" until the milestone itself ships (which may be days later, or never, if abandoned). This is the dominant cause of `feat/*` branches accumulating for a milestone/feature cluster.
 - **Squash merges.** If a branch was merged via squash (manual UI merge, or org/branch-protection settings that force squash-only), the resulting commit is a brand-new SHA that is never an ancestor of the original branch — so ancestry-based detection never matches it, even though the PR is clearly `MERGED` on GitHub.
 
 Both gaps disappear when merged-PR head-refs (regardless of base branch or merge strategy) are used directly as the deletion set:

package/commands/deploy-pr.md

@@ -8,6 +8,8 @@ allowed-tools: Bash, Read, Grep, Glob, Skill
 
 # /deploy-pr — PR Ship Orchestrator
 
+> **Skill names**: `{FORGE_SKILL_PREFIX}` is `forgedock:` (plugin install) or empty (`install.sh`), resolved once per run by `commands/work-on.md` § Skill Name Resolution. If the skill is not found under either name, STOP and report "skill not found" — never run the phase inline.
+
 **Input**: $ARGUMENTS
 
 **NEVER use plan mode (EnterPlanMode)** — it breaks execution context.
@@ -146,7 +148,7 @@ fi
 echo "Source: $SOURCE → Target: $PR_TARGET (prefix: $TITLE_PREFIX)"
 ```
 
-**Routing guard — staging→main**: When `SOURCE=staging` and `PR_TARGET=main`, the review gate (Phase 4) MUST route to `Skill("review-pr-staging", ...)` rather than the standard `review-pr`. This ensures the staging deploy review (comprehensive, multi-agent) runs instead of the single-PR review.
+**Routing guard — staging→main**: When `SOURCE=staging` and `PR_TARGET=main`, the review gate (Phase 4) MUST route to `Skill("{FORGE_SKILL_PREFIX}review-pr-staging", ...)` rather than the standard `review-pr`. This ensures the staging deploy review (comprehensive, multi-agent) runs instead of the single-PR review.
 
 **Routing guard — milestone→staging**: When `SOURCE` matches `milestone/*`, this is a feature lane ship. `/review-pr` handles these normally (they target staging, not main).
 
@@ -285,12 +287,14 @@ FIX_CI_AVAILABLE=$(ls ~/.claude/commands/fix-ci.md 2>/dev/null && echo "true" ||
 
 if [ "$FIX_CI_AVAILABLE" = "false" ]; then
   echo "WARNING: /fix-ci not available — skipping CI gate. Install fix-ci (issue #1675) for automated CI fixing."
-  echo "CI gate: SKIPPED (fix-ci unavailable)"
-  CI_GATE_PASSED=true  # Allow pipeline to continue; review gate will catch CI failures
+  echo "CI fix loop: SKIPPED (fix-ci unavailable) — the Phase 5 CI gate still blocks a red merge"
+  CI_GATE_PASSED=true  # the fix loop is skipped, not the gate: Phase 5 runs wait-ci-green.sh before merging
 else
   # Check current CI status
-  CURRENT_CI_STATUS=$(gh pr checks "$PR_NUMBER" $GH_FLAG --json name,status,conclusion \
-    --jq '[.[] | select(.conclusion == "failure")] | length' 2>/dev/null || echo "0")
+  # Fail closed: valid fields only (`status`/`conclusion` do not exist on gh pr checks --json; the
+  # old query errored and defaulted to 0 = "no failures"). An unreadable result counts as failing.
+  CURRENT_CI_STATUS=$(gh pr checks "$PR_NUMBER" $GH_FLAG --json name,bucket \
+    --jq '[.[] | select(.bucket == "fail" or .bucket == "cancel")] | length' 2>/dev/null || echo "1")
 
   if [ "$CURRENT_CI_STATUS" -eq 0 ]; then
     echo "CI gate: PASSED (no failing checks)"
@@ -303,7 +307,7 @@ else
       echo "=== CI Gate Iteration $CI_ITER / $MAX_CI_ITER ==="
 
       if [ "$DRY_RUN" = "false" ]; then
-        Skill("fix-ci", args="$PR_NUMBER $GH_FLAG")
+        Skill("{FORGE_SKILL_PREFIX}fix-ci", args="$PR_NUMBER $GH_FLAG")
       else
         echo "[DRY-RUN] Would invoke: Skill(fix-ci, $PR_NUMBER $GH_FLAG)"
       fi
@@ -356,9 +360,9 @@ while [ "$REVIEW_ITER" -lt "$MAX_REVIEW_ITER" ] && [ "$REVIEW_GATE_PASSED" = "fa
   if [ "$DRY_RUN" = "false" ]; then
     # Route: staging→main uses review-pr-staging; all other uses standard review-pr
     if [ "$SOURCE" = "$STAGING_BRANCH" ] && [ "$PR_TARGET" = "$DEFAULT_BRANCH" ]; then
-      REVIEW_RESULT=$(Skill("review-pr-staging", args="$PR_NUMBER $GH_FLAG"))
+      REVIEW_RESULT=$(Skill("{FORGE_SKILL_PREFIX}review-pr-staging", args="$PR_NUMBER $GH_FLAG"))
     else
-      REVIEW_RESULT=$(Skill("review-pr", args="$PR_NUMBER $GH_FLAG"))
+      REVIEW_RESULT=$(Skill("{FORGE_SKILL_PREFIX}review-pr", args="$PR_NUMBER $GH_FLAG"))
     fi
   else
     echo "[DRY-RUN] Would invoke review-pr for PR #$PR_NUMBER"
@@ -425,9 +429,25 @@ if [ "$DRY_RUN" = "true" ]; then
   echo "[DRY-RUN] Would merge PR #$PR_NUMBER (${SOURCE} → ${PR_TARGET})"
   MERGE_STATUS="dry_run"
 else
-  echo "Merging PR #$PR_NUMBER..."
-  MERGE_OUTPUT=$(gh pr merge "$PR_NUMBER" $GH_FLAG --merge 2>&1)
-  MERGE_EXIT=$?
+  # CI gate (MANDATORY before any autonomous merge): wait for every check, merge only if all are
+  # green, and merge exactly the commit the gate checked.
+  _l="$(readlink -f "$HOME/.claude/commands/work-on.md" 2>/dev/null || true)"; _l="${_l%/commands/work-on.md}"
+  CI_GATE_SCRIPT=""
+  for _c in '${CLAUDE_PLUGIN_ROOT}' "${FORGE_ROOT:-}" "${FORGEDOCK_HOME:-}" "${FORGE_HOME:-}" "$_l"; do
+    case "$_c" in /*) [ -z "$CI_GATE_SCRIPT" ] && [ -f "$_c/scripts/wait-ci-green.sh" ] && CI_GATE_SCRIPT="$_c/scripts/wait-ci-green.sh" ;; esac
+  done
+  if [ -n "$CI_GATE_SCRIPT" ]; then CI_GATE_OUT=$(bash "$CI_GATE_SCRIPT" "$PR_NUMBER" $GH_FLAG); CI_GATE_RC=$?
+  else CI_GATE_OUT="CI_GATE: ERROR — scripts/wait-ci-green.sh not resolvable (fail closed)"; CI_GATE_RC=2; fi
+  echo "$CI_GATE_OUT"
+  GATED_HEAD=$(printf '%s\n' "$CI_GATE_OUT" | sed -n 's/^CI_GATE_HEAD: //p' | head -1)
+  # rc 3 = CI still running: re-run this block (up to 3 more times) before treating it as a failure.
+  if [ "$CI_GATE_RC" -ne 0 ]; then
+    MERGE_OUTPUT="not merged: CI gate rc=${CI_GATE_RC}"; MERGE_EXIT=1
+  else
+    echo "Merging PR #$PR_NUMBER..."
+    MERGE_OUTPUT=$(gh pr merge "$PR_NUMBER" $GH_FLAG --merge --match-head-commit "$GATED_HEAD" 2>&1)
+    MERGE_EXIT=$?
+  fi
 
   if [ "$MERGE_EXIT" -eq 0 ]; then
     echo "Merged PR #$PR_NUMBER successfully"

package/commands/geo-audit.md

@@ -7,6 +7,8 @@ install: extras
 
 # /geo-audit — GEO Discoverability Audit & Issue Generator
 
+> **Skill names**: `{FORGE_SKILL_PREFIX}` is `forgedock:` (plugin install) or empty (`install.sh`), resolved once per run by `commands/work-on.md` § Skill Name Resolution. If the skill is not found under either name, STOP and report "skill not found" — never run the phase inline.
+
 You are the GEO (Generative Engine Optimization) auditor. Pull AI referral data from Umami and Clarity, check every public page for GEO compliance (structured data, OG tags, freshness, sitemap, llms.txt), and auto-create GitHub issues for gaps.
 
 **You have access to ALL tools** — MCP tools for Clarity, Bash for Umami/curl checks, gh CLI for issues.
@@ -360,7 +362,7 @@ BODY_EOF
 ```
 
 ```
-Skill(skill="issue", args="--title \"{fix|feat}: {concise description}\" --body-file \"$GEO_BODY_FILE\" --label \"{priority}\" --label \"seo\" --label \"geo\"")
+Skill(skill="{FORGE_SKILL_PREFIX}issue", args="--title \"{fix|feat}: {concise description}\" --body-file \"$GEO_BODY_FILE\" --label \"{priority}\" --label \"seo\" --label \"geo\"")
 ```
 
 `{priority}`, `seo`, and `geo` are each passed as their own `--label` flag — `/issue`'s programmatic mode does not comma-split a single `--label` value. Every row in the Phase 3 table maps to the `seo,geo` label pair, so both are passed as separate literal `--label` flags rather than a single `{labels}` placeholder.

package/commands/incident-response.md

@@ -8,6 +8,8 @@ install: extras
 
 # /incident-response — P0 Incident Coordination
 
+> **Skill names**: `{FORGE_SKILL_PREFIX}` is `forgedock:` (plugin install) or empty (`install.sh`), resolved once per run by `commands/work-on.md` § Skill Name Resolution. If the skill is not found under either name, STOP and report "skill not found" — never run the phase inline.
+
 **Input**: $ARGUMENTS
 
 **Config variables used by this command** (set in `forge.yaml`):
@@ -364,7 +366,7 @@ See postmortem: #{INCIDENT_NUMBER} (comment)
 BODY_EOF
 # Route through the /issue create-hook (canonical dedup + body validation) instead of a raw
 # `gh issue create`.
-Skill(skill="issue", args="--title \"$ACTION_ITEM_TITLE\" --body-file \"$ACTION_ITEM_BODY_TMPFILE\" --label \"{type_label}\" --label \"P{priority}\"")
+Skill(skill="{FORGE_SKILL_PREFIX}issue", args="--title \"$ACTION_ITEM_TITLE\" --body-file \"$ACTION_ITEM_BODY_TMPFILE\" --label \"{type_label}\" --label \"P{priority}\"")
 rm -f "$ACTION_ITEM_BODY_TMPFILE"
 trap - EXIT
 ACTION_ITEM_NUMBER=$(gh issue list \

package/commands/issue.md

@@ -7,13 +7,15 @@ argument-hint: "[description of the problem or feature] [--dry-run] | --title \"
 
 # /issue — Deterministic Issue Creator
 
+> **Skill names**: `{FORGE_SKILL_PREFIX}` is `forgedock:` (plugin install) or empty (`install.sh`), resolved once per run by `commands/work-on.md` § Skill Name Resolution. If the skill is not found under either name, STOP and report "skill not found" — never run the phase inline.
+
 **Input**: $ARGUMENTS
 
 You create GitHub issues with the exact structure the `/work-on` pipeline expects. Every issue you create must give the investigation agent enough context to find the right files on the first pass — no vague descriptions, no missing domains, no ambiguous scope.
 
 `/issue` is the structured create-hook for issue creation across the pipeline — it enforces the canonical template, reads code before drafting, runs dedup, and validates mandatory sections. Because those checks are deterministic, `/issue` **creates the issue by default once they pass** — it does not wait for a human to approve the draft. Pass `--dry-run` to review the draft without creating anything (see Argument Parsing below).
 
-`/issue` also accepts a **programmatic invocation form** for callers that have already composed a title, body, labels, and (optionally) a milestone — e.g. `Skill(skill="issue", args="--title \"fix: ...\" --body-file \"$BODY_FILE\" --label bug --label P2")` (the caller writes the body to that path before invoking). This form skips the free-text parsing (Phase 1) and LLM drafting (Phase 3) entirely, but still runs the same dedup and body-validation correctness gates as the interactive path. See **Programmatic Invocation Contract** below — every `--body-file` caller must use an entity- and agent-scoped scratch path and include a unique integrity marker which `/issue` verifies after creation. This is required because a collision can substitute plausible but unrelated content, not just produce an obvious file error (forge#2843).
+`/issue` also accepts a **programmatic invocation form** for callers that have already composed a title, body, labels, and (optionally) a milestone — e.g. `Skill(skill="{FORGE_SKILL_PREFIX}issue", args="--title \"fix: ...\" --body-file \"$BODY_FILE\" --label bug --label P2")` (the caller writes the body to that path before invoking). This form skips the free-text parsing (Phase 1) and LLM drafting (Phase 3) entirely, but still runs the same dedup and body-validation correctness gates as the interactive path. See **Programmatic Invocation Contract** below — every `--body-file` caller must use an entity- and agent-scoped scratch path and include a unique integrity marker which `/issue` verifies after creation. This is required because a collision can substitute plausible but unrelated content, not just produce an obvious file error (forge#2843).
 
 **Agent model policy**: `model: "{DEFAULT_MODEL}"` — resolved from forge.yaml `agents.default_model`, else "sonnet" (standard tier). Fallback: `model: "opus"` if rate-limited. Feature gate: pass `effort` in Task/Skill spawns only on Claude Code >= 2.1.154.
 **NEVER use plan mode (EnterPlanMode).**
@@ -43,7 +45,7 @@ PROGRAMMATIC_MILESTONE=""
 PROGRAMMATIC_EXCLUDE=""
 
 # Positional/flag parsing. $ARGUMENTS is a single opaque string (the invoking
-# agent's raw args, e.g. from `Skill(skill="issue", args="--title \"fix: ...\" ...")`)
+# agent's raw args, e.g. from `Skill(skill="{FORGE_SKILL_PREFIX}issue", args="--title \"fix: ...\" ...")`)
 # — it is NOT pre-tokenized by any harness, and a naive `ARGS=($ARGUMENTS)` would
 # word-split on whitespace without honoring embedded quote characters (a literal
 # `"` inside the string is not shell syntax at this point), fragmenting any